Skip to main content

​
Error format

Developer API errors use stable machine-readable codes: 
{ "error": "INVALID_INPUT" }
Some errors include additional structured fields, such as credit balances or retry timing. Do not depend on English error messages in production clients.

​
Common codes

HTTP statusCodeMeaning
400INVALID_INPUTInvalid JSON, invalid UUID, unsupported status filter, invalid request shape, unknown field, empty patch body, or another validation failure.
400INPUT_TOO_LARGERealtime run input is larger than the public request limit.
401AUTHENTICATION_REQUIREDAccount API key is missing, malformed, revoked, or unknown.
402INSUFFICIENT_CREDITSThe account does not have enough credits to start the run.
403ACCOUNT_BLOCKEDThe account is blocked from running.
404AGENT_NOT_FOUNDThe agent is missing, inactive, deleted, not personal, or outside the account boundary.
404CONVERSATION_NOT_FOUNDThe conversation is missing or outside the account boundary.
404RUN_NOT_FOUNDThe run is missing or outside the account boundary.
429RATE_LIMITEDAccount-level or IP-level rate limit exceeded.
503SERVICE_UNAVAILABLEAgent dispatch or Platform write path was unavailable before the request was accepted.
Async /v1/runs reports oversized input as INVALID_INPUT. Realtime /v1/realtime/runs reports oversized input as INPUT_TOO_LARGE before the stream opens.

​
Credit errors

Credit errors can include available and required values: 
{
  "error": "INSUFFICIENT_CREDITS",
  "available": 0,
  "required": 1000
}

​
Rate-limit errors

Rate-limit responses include a Retry-After header when a retry delay is available. 
HTTP/1.1 429 Too Many Requests
Retry-After: 60

​
Stream failures

For realtime runs, failures that happen before the stream opens return normal JSON errors. Failures after the stream opens are sent as terminal events: 
event: run.failed
data: {"run_id":"11111111-1111-4111-8111-111111111111","status":"failed","error":{"code":"EXECUTION_FAILED"}}