Handle consistent JSON errors and HTTP status codes.
The API uses standard HTTP status codes. Error responses have a stable JSON shape:
{
"name": "insufficient_scope",
"message": "This API key does not have the required conversations:read permission."
}| Status | Name | Meaning |
|---|---|---|
400 | bad_request | A path or query parameter is invalid. |
401 | unauthorized | The API key is missing, invalid, or revoked. |
403 | insufficient_scope | The key is valid but lacks the operation's permission. |
404 | not_found | The requested resource does not exist for this Agent. |
429 | rate_limited | A key, Agent, or source IP exceeded its per-minute request limit. |
500 | internal_server_error | The request failed unexpectedly. |
503 | service_unavailable | The API is temporarily unavailable; the request was not processed. |
401 responses include WWW-Authenticate: Bearer. A 403 response includes an
insufficient_scope Bearer challenge naming the permission the key needs.
Retry 500 and 503 failures with capped exponential backoff and jitter. For 429 and 503 responses, wait at least the number of seconds in the Retry-After header before sending another request. A fail-closed 503 caused by unavailable rate-limit storage returns Retry-After: 60.
Do not automatically retry 400, 401, 403, or 404 responses. Correct the request, supply a valid key, or add the required permission first.
A 404 response does not reveal whether a resource exists for a different Agent. Resources are
always resolved within the Agent associated with the API key.