Errors

OrgX APIs return standard HTTP status codes with JSON bodies. Preview REST endpoints may use either a simple error shape or the richer structured error shape used by newer route handlers.

HTTP Status Codes

Code	Meaning
`200`	Success
`201`	Created
`400`	Invalid request or validation error
`401`	Missing, invalid, or revoked authentication
`403`	Authenticated, but not permitted
`404`	Resource not found in the caller’s workspace
`409`	Conflict or invalid resource state
`429`	Rate limited
`500`	Internal server error
`502`	Upstream integration error
`504`	Query or upstream timeout

Simple Error Shape

Some preview endpoints return a compact body:

{
  "error": "Unauthorized",
  "message": "Valid API key required. Get your key from OrgX settings."
}

Structured Error Shape

Newer endpoints return a structured object:

{
  "error": {
    "code": "not_found",
    "message": "Task 2f7b2f47-2d7a-4d65-81d0-5c4b0f9b7e01 not found",
    "status": 404,
    "request_id": "req_01h..."
  }
}

Fields

Field	Type	Description
`error`	string or object	Human-readable error or structured error object
`message`	string	Additional human-readable context
`error.code`	string	Machine-readable error code
`error.status`	number	HTTP status code
`error.request_id`	string	Support and trace identifier

Retrying Errors

Status	Retry?	Guidance
`400`	No	Fix the request body or query params.
`401`	No	Rotate or replace the API key.
`403`	No	Check workspace access and scopes.
`404`	Usually no	Confirm the resource belongs to the API key’s workspace.
`409`	Depends	Re-read the resource state before retrying.
`429`	Yes	Back off and retry after the reset window.
`500`	Yes	Retry with an idempotency key for writes.
`504`	Yes	Retry reads; retry writes only when the endpoint supports idempotency.

Getting Started

Connect Your Tools

Agent Ops

Platform

API Reference

Resources

HTTP Status Codes

Simple Error Shape

Structured Error Shape

Fields

Retrying Errors

​HTTP Status Codes

​Simple Error Shape

​Structured Error Shape

​Fields

​Retrying Errors

HTTP Status Codes

Simple Error Shape

Structured Error Shape

Fields

Retrying Errors