Errors

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 status	Code	Meaning
`400`	`INVALID_INPUT`	Invalid JSON, invalid UUID, unsupported status filter, invalid request shape, unknown field, empty patch body, or another validation failure.
`400`	`INPUT_TOO_LARGE`	Realtime run input is larger than the public request limit.
`400`	`MODEL_NOT_SUPPORTED`	The requested `model` id is unknown, retired, rollout-hidden, malformed, or not supported on the Developer API.
`401`	`AUTHENTICATION_REQUIRED`	Account API key is missing, malformed, revoked, or unknown.
`402`	`INSUFFICIENT_CREDITS`	The account does not have enough credits to start the run.
`403`	`ACCOUNT_BLOCKED`	The account is blocked from running.
`403`	`MODEL_NOT_ALLOWED`	The requested model exists, but the account’s plan or model-access entitlement cannot run it.
`400`	`SECRET_NAME_INVALID`	Secret name is empty, too long, or not an uppercase env-var identifier.
`400`	`SECRET_NAME_RESERVED`	Secret name collides with a platform-managed environment variable.
`400`	`SECRET_VALIDATION`	Secret value is empty or larger than 8 KB, or description is too long.
`400`	`SECRET_LIMIT_REACHED`	The account already has 50 secrets.
`400`	`SKILL_NAME_INVALID`	Skill name or `skill_id` is empty, too long, or not a valid identifier.
`400`	`SKILL_NAME_CONFLICT`	The custom skill name collides with a built-in skill.
`400`	`SKILL_ALWAYS_ON`	A core built-in skill cannot be enabled or disabled.
`400`	`SKILL_NOT_REFRESHABLE`	The skill is not a GitHub-sourced custom skill.
`400`	`INVALID_GITHUB_URL`	`source_url` is missing or is not a GitHub repository URL.
`400`	`SKILL_CONTENT_TOO_LARGE`	`SKILL.md` exceeds 256 KB or supporting files exceed 5 MB.
`400`	`UNSUPPORTED_FILE_TYPE`	The uploaded workspace file type is outside the web Files allowlist.
`404`	`AGENT_NOT_FOUND`	The agent is missing, inactive, deleted, not personal, or outside the account boundary.
`404`	`WORKSPACE_NOT_FOUND`	The workspace is missing, is a team workspace, or is outside the account boundary.
`404`	`FILE_NOT_FOUND`	The file is missing, is not a workspace-root upload, or does not belong to this agent or workspace.
`404`	`SECRET_NOT_FOUND`	No secret with that name exists for this account.
`404`	`SKILL_NOT_FOUND`	The skill is missing, is a core built-in on GET, or is outside the account boundary.
`404`	`CONVERSATION_NOT_FOUND`	The conversation is missing or outside the account boundary.
`404`	`RUN_NOT_FOUND`	The run is missing or outside the account boundary.
`409`	`DUPLICATE_WORKSPACE_NAME`	A personal workspace with this name already exists.
`409`	`WORKSPACE_MISMATCH`	The conversation is already bound to a different `workspace_id`.
`409`	`SECRET_CONFLICT`	A secret with this name already exists.
`413`	`FILE_TOO_LARGE`	The uploaded workspace file exceeds the account size limit (10 MB, or 100 MB on Volume).
`429`	`RATE_LIMITED`	Account-level or IP-level rate limit exceeded.
`503`	`SERVICE_UNAVAILABLE`	Agent 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. Use GET /v1/models to discover supported model ids and account-specific availability before sending a model field.

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"}}

Get Started

Agents

Agent Memory

Agent Files

Runs

Models

Workspaces

Workspace Files

Secrets

Skills

Concepts

Error format

Common codes

Credit errors

Rate-limit errors

Stream failures

​Error format

​Common codes

​Credit errors

​Rate-limit errors

​Stream failures

Error format

Common codes

Credit errors

Rate-limit errors

Stream failures