Errors

The API uses standard HTTP status codes. All error responses share a consistent JSON envelope.

Error response format

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": {
    "amount": "must be greater than 0",
    "email": "must not be blank"
  }
}

Rate limit errors (429)

429 Too Many Requests responses do not use the standard {code, message, details} envelope. Instead they return an OAuth-style body with error and error_description fields:

{
  "error": "rate_limit_exceeded",
  "error_description": "Too many requests. Limit: 60 requests/minute. Retry after 1710500000"
}

See the Rate limits guide for per-environment limits and retry guidance.

HTTP status codes

Status	Meaning
`200 OK`	Success
`201 Created`	Resource created
`204 No Content`	Deleted or no body
`400 Bad Request`	Invalid request body or parameters
`401 Unauthorized`	Missing or invalid Bearer token
`403 Forbidden`	Valid token, insufficient scope or wrong org
`404 Not Found`	Resource does not exist
`422 Unprocessable Entity`	Business rule violation
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error

Error codes

Code	Description
`VALIDATION_ERROR`	One or more fields failed validation
`BUSINESS_RULE_VIOLATION`	Allowed state transition violated (e.g. canceling a completed order)
`RESOURCE_NOT_FOUND`	The requested resource does not exist in your organization
`ORG_MISMATCH`	Resource belongs to a different organization
`INSUFFICIENT_SCOPE`	Token does not have the required scope
`INTERNAL_ERROR`	Unexpected server error — include X-Request-Id when reporting