Errors

HTTP status codes and the JSON error envelope returned by the API.

The API uses conventional HTTP status codes. 2xx codes indicate success, 4xx codes indicate a problem with the request (a missing parameter, a failed validation, an authentication or permission error), and 5xx codes indicate a server-side error.

Status codes

Code	Meaning
`200`	Success.
`400`	Bad request — the request was malformed.
`401`	Unauthorized — the token is missing or invalid.
`403`	Forbidden — the token lacks the required scope.
`404`	Not found.
`409`	Conflict — the request conflicts with an existing operation or idempotency key.
`422`	Unprocessable — validation failed.
`429`	Too many requests — you are being rate limited.
`500`	Server error — something went wrong on our side.

Error payload

Errors return a standard JSON envelope:

json

{
  "error": true,
  "error_code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "errors": []
  }
}

Always branch on the HTTP status code first, then inspect error_code for machine-readable handling. The message field is human-readable and may be clarified over time. When present, details contains structured context such as validation failures or a missing scope.

Every error response also includes the X-Correlation-ID response header. Include that id when contacting support.