Error codes

Every Declaw error response carries a human-readable message. Responses with status 403 also carry a machine-readable code. Branch on code, not on message. Messages are prose written for a person reading a stack trace, and they get reworded. code is API surface and is treated as such.

{
  "message": "command blocked (IMDS access): curl http://169.254.169.254/",
  "code": "policy_denied"
}

A 403 is not an authentication failure

This trips people up, so it is worth stating plainly: a bad, missing, expired, or revoked API key returns 401. If you got a 403, your credentials were accepted. Something else stopped the request. 403 covers several unrelated situations:

`code`	What happened	Who can fix it
`policy_denied`	A security policy blocked this action — an OPA gate, the command scanner, an egress rule.	The operator who set the policy
`forbidden`	The resource belongs to another account, team, or owner.	Nobody — you are asking for someone else’s data
`tier_limit`	Your plan’s ceiling was reached (vCPU, memory, disk, session length, snapshot storage).	You, by upgrading or asking for less
`not_approved`	The account has not cleared the waitlist.	Declaw, by approving you
`email_not_verified`	The email address is unverified.	You, by clicking the link
`admin_forbidden`	The admin surface rejected the request.	The operator holding the admin secret

`policy_denied` is Declaw working

The other codes are problems. policy_denied is the product doing its job — an agent attempted something the operator forbade, and it was stopped. That distinction matters for how you handle it. A policy_denied is usually not an error in your integration; it is an event your users may want to see:

from declaw import Sandbox

sbx = Sandbox.create(template="python")
result = sbx.commands.run("curl http://169.254.169.254/latest/meta-data/")

declaw.exceptions.AuthenticationError:
  HTTP 403: command blocked (IMDS access): curl http://169.254.169.254/

The SDKs currently raise an authentication error for every 403, including policy denials — the type is misleading even though the message is correct. Until a dedicated error type ships, read code off the response body rather than relying on the exception class, and do not treat these as credential problems.

Command, PTY, and stdio denials are decided by a gate running inside the sandbox. Those responses carry code too — it is applied as the response leaves the host, so you get the same envelope regardless of which layer made the decision.

Denials are audited

Most policy denials are recorded in the audit trail, so you can reconstruct what was blocked without parsing error strings. Command, PTY, and stdio denials also carry the compliance control IDs that fired — both in the audit entry and on the X-Declaw-Policy-Controls response header — so you can see which governance control each denial satisfied. Not every denial produces an audit entry today; a request refused because the sandbox has public traffic disabled, for example, does not. See Audit logging for retrieval.

Other statuses

Status	Meaning
`400` / `422`	The request was malformed or failed validation.
`401`	Credentials missing, invalid, expired, or revoked.
`402`	Insufficient balance. The body carries `wallet_type`.
`404`	Not found. Some resources — template build logs among them — also return `404` when the resource belongs to another tenant, so the response cannot confirm it exists. Sandboxes instead return `403` with `code: forbidden` in that case.
`409`	Conflict, such as a duplicate alias or a version mismatch.
`413`	Payload too large.
`429`	Rate limited. A `Retry-After` header carries the backoff.

Revoking an API key takes effect within about 60 seconds — credentials are cached briefly. Plan for that window if key revocation is part of your incident response.

Getting Started

Core Features

CLI

Security

Platform

Deployment

Architecture

A 403 is not an authentication failure

`policy_denied` is Declaw working

Denials are audited

Other statuses

​A 403 is not an authentication failure

​policy_denied is Declaw working

​Denials are audited

​Other statuses

A 403 is not an authentication failure

`policy_denied` is Declaw working

Denials are audited

Other statuses