Errors

Handle one structured JSON error envelope across OrgX REST API v1.

Errors use one envelope:

{
  "error": {
    "code": "validation_failed",
    "message": "Title is required",
    "details": { "field": "title" },
    "requestId": "req_01J5YB8X4Y",
    "timestamp": "2026-08-18T18:30:00.000Z"
  }
}

Branch on the HTTP status and error.code. When requestId is present, log it and include it when you contact support.

Status	Meaning	Retry
400	Invalid request	Fix the request
401	Missing or invalid authentication	Fix or rotate the key
403	The caller lacks permission	Change scope or access
404	The resource is unavailable in this workspace	Check the ID and workspace
409	State or idempotency conflict	Read current state before deciding
413	Request exceeds the documented size	Reduce the body
422	The JSON fails the resource schema	Fix the reported issue paths
429	Rate limit reached	Honor Retry-After
500	Unexpected server error	Retry only with an idempotency key
503	A required service is temporarily unavailable	Back off and retry
504	A dependency timed out	Retry reads; retry writes with the same key

Validation endpoints may add bounded issues with JSON Pointer paths. The outer error envelope remains the programmatic contract.

Error codes

Codes are lowercase snake_case. The shared vocabulary is:

Code	Status	Meaning
bad_request	400	The request format is invalid
validation_failed	400	The request failed schema validation
unauthorized	401	Auth is missing or invalid
forbidden	403	The caller lacks permission
not_found	404	The resource does not exist here
conflict	409	State conflict
budget_exceeded	402	Autonomy budget depleted
plan_limit_reached	403	Plan quota exceeded
rate_limited	429	Too many requests
internal_error	500	Unexpected server error
integration_error	502	An external service failed
service_unavailable	503	A dependency is unavailable
timeout	504	The request timed out
missing_idempotency_key	400	A mutation did not include Idempotency-Key
idempotency_key_conflict	409	The key was reused with a different payload
lifecycle_action_failed	422	The requested lifecycle transition was refused

Individual resources add their own codes on top of these — for example missing_idempotency_key, handoff_conflict, operating_process_conflict, discovery_run_in_progress, invalid_agent_work_receipt, and direct_human_decision_action_required. Mutations also use idempotency_key_conflict for retry protection. Those are documented on each resource’s page. Branch on the HTTP status first and the code second, so an unfamiliar resource-specific code still routes to the right handling.

The MCP tool surface uses a different vocabulary

MCP tool errors are not these codes. That surface has its own set — invalid_input, auth_required, permission_denied, entity_not_found, stale_version, rate_limit_exceeded, server_error, and others — documented in the failure playbooks. The two vocabularies are not aliases of each other; do not map one onto the other in client code.

Condition	REST v1	MCP tools
Validation failed	validation_failed	invalid_input
Auth missing or invalid	unauthorized	auth_required
Caller lacks permission	forbidden	permission_denied
Resource not found	not_found	entity_not_found
Concurrency conflict	conflict (or a resource-specific *_conflict)	stale_version
Rate limited	rate_limited	rate_limit_exceeded
Unexpected server error	internal_error	server_error

Retry timing differs with the surface too: REST v1 sends Retry-After; the MCP edge sends X-RateLimit-Reset alongside X-RateLimit-Limit and X-RateLimit-Remaining. Honor whichever the response you are holding carries.