Errors and HTTP status codes

Every response includes data, error and request_id. On success, error is null. On failure, data is null and error explains the problem.

Error envelope

{
  "data": null,
  "error": {
    "code": "validation_error",
    "message": "Check the fields and try again.",
    "details": {}
  },
  "request_id": "req_01..."
}

How to react

• 400 or 422: fix the payload; do not retry unchanged.
• 401: check the API key and header name.
• 403: check permissions and IP restrictions.
• 404: verify the public id and environment.
• 409: inspect the conflicting resource or idempotency key.
• 429: wait, then retry with exponential backoff.
• 5xx: retry a limited number of times using the same idempotency key.

Always include request_id when contacting support.