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": {
    "unitPrice": "must be greater than 0",
    "currencyCode": "must not be blank"
  }
}

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