Errors and failure handling

Interpret the stable error envelope and decide whether to correct, reload, reconcile, or stop.

Last updated: 9/13/2026

API failures use a stable JSON envelope. Messages are safe for display, while the request ID is the correlation value to include in a support report.

JSON

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "requestId": "req-123"
  }
}

Response strategy

Status	Meaning	Caller action
`400`	Request validation failed	Correct the declared parameters, headers, or body.
`401`	Authentication or session bootstrap is required	Refresh the Privy session and bootstrap if needed.
`403`	The authenticated caller lacks authority	Stop; do not retry under the same authority.
`404`	The resource is unavailable in the authorized scope	Confirm the organization and resource identifiers.
`409`	Version, state, or idempotency conflict	Reload current state and reconcile the intended action.
`422`	Deterministic policy refused the action	Show the refusal; model output cannot override it.
`429`	A bounded quota was reached	Respect the response and retry policy.
`503`	A required dependency is unavailable	Back off and reconcile before retrying a mutation.

Do not parse message text to decide control flow. Branch on the HTTP status and stable error.code, and log only the request ID plus sanitized application context.

Safe mutations and retries API reference