Errors
Problem details, error codes, and how to handle them.
Errors are RFC 9457 problem details with the media type
application/problem+json.
{
"type": "about:blank",
"title": "No compliant model",
"status": 503,
"code": "no_compliant_model",
"detail": "No model deployment satisfies this client's region and retention rules.",
"request_id": "6f1c2a9b0d4e4f7a8b3c5d6e7f809a1b",
"issues": []
}| Field | Meaning |
|---|---|
status | The HTTP status code |
code | A machine-readable code. Branch on this, not on title or detail. |
title, detail | Human-readable summary and explanation |
request_id | Also in the X-Request-Id response header. Quote it when you contact support. |
issues | For validation errors: one entry per field, with a JSON Pointer path and a message |
Codes
The set of codes is open: treat a code you do not recognise as a generic error for its status.
| Code | Typical status | Meaning |
|---|---|---|
unauthenticated | 401 | No token, or the token is not valid |
credential_revoked | 401 | The credential was revoked |
forbidden | 403 | Authenticated, but not allowed |
not_found | 404 | No such object, or not visible to you |
conflict | 409 | A version or state conflict, for example a stale compliance profile version |
validation_failed | 422 | The request does not match the contract; see issues |
rate_limited | 429 | Too many requests or tokens for this credential or client |
not_implemented | 501 | Defined in the contract, not built yet |
no_compliant_model | 503 | No model deployment satisfies the client's rules |
budget_exceeded | A hard budget stopped the call | |
limit_hit | A run limit was reached | |
feature_not_allowed | The feature is switched off for this caller | |
tool_unavailable, tool_not_reviewed | A tool could not be used | |
kill_switch_active, workspace_suspended | An administrator stopped this agent, client, credential, project or workspace | |
verify_failed, awaiting_input_expired, cancelled | A run ended this way | |
schema_drift | A pinned tool schema changed and needs review | |
wrong_geo | 421 | The request reached the wrong geo for this credential; geo_id names the right one |
placement_moved | 409 | The workspace moved while the request ran; retry it |
policy_stale | 503 | Policy could not be confirmed as current, so a risky action was refused; retry after Retry-After |
overloaded | 503 | The service is shedding load; retry after Retry-After |
idempotency_conflict | 409 | The Idempotency-Key was already used with a different body or route |
idempotency_in_progress | 409 | A request with this Idempotency-Key is still running; retry after Retry-After |
precondition_failed | 412 | The If-Match value is stale: read the object again |
replay_expired | 410 | The stream position in after is older than what is kept |
outcome_unknown | 409 | A tool's effect is unknown and is being reconciled; it is never retried automatically |
incomplete | 409 | An export could not include every source; exports are complete or they fail |
approval_mismatch | 409 | The approval does not match the exact tool call it was shown for |
internal_error | 500 | Something went wrong on our side |
When the status is 401, the response also carries WWW-Authenticate: Bearer.