Skip to main content
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

CodeMeaning
200Success
201Created
400Invalid request or validation error
401Missing, invalid, or revoked authentication
403Authenticated, but not permitted
404Resource not found in the caller’s workspace
409Conflict or invalid resource state
429Rate limited
500Internal server error
502Upstream integration error
504Query 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

FieldTypeDescription
errorstring or objectHuman-readable error or structured error object
messagestringAdditional human-readable context
error.codestringMachine-readable error code
error.statusnumberHTTP status code
error.request_idstringSupport and trace identifier

​
Retrying Errors

StatusRetry?Guidance
400NoFix the request body or query params.
401NoRotate or replace the API key.
403NoCheck workspace access and scopes.
404Usually noConfirm the resource belongs to the API key’s workspace.
409DependsRe-read the resource state before retrying.
429YesBack off and retry after the reset window.
500YesRetry with an idempotency key for writes.
504YesRetry reads; retry writes only when the endpoint supports idempotency.