Errors
HTTP status codes
| Status | Meaning |
|---|---|
200 |
Success. |
400 |
Bad request. A parameter is missing or invalid, or the request cannot be processed as sent. |
401 |
Unauthorized. The API key is missing or invalid. |
403 |
Forbidden. The API key is valid, but your partner account does not have access to this feature or resource. |
404 |
Not found. The endpoint or resource does not exist. |
5xx |
A server-side problem. Retry later with backoff. |
Error envelope
Every error has the same shape, with the details inside an error object:
{
"error": {
"code": "DATA.PRODUCT",
"ns": "DATA",
"message": "The selected product is currently unavailable",
"data": { "field": "product_id" },
"status": 400
}
}| Field | Type | Description |
|---|---|---|
code |
string | Stable, namespaced identifier (NAMESPACE.IDENTIFIER). Use this for programmatic handling. |
ns |
string | The error namespace, the part before the dot (for example DATA). |
message |
string | Human-readable description, suitable for display. |
status |
integer | The HTTP status code, repeated in the body. |
data |
object | Optional context. Often carries the offending field; validation errors carry fields instead. |
id |
string | Optional. Present on some errors, for example data.request_validation on validation errors. |
Validation errors
A request that fails validation returns 400 with the code DATA.INVALID. data.fields maps each invalid field to a list of problems, each with its own code and message:
{
"error": {
"code": "DATA.INVALID",
"ns": "DATA",
"message": "Request contains errors",
"data": {
"fields": {
"limit": [
{ "code": "number.max", "message": "Must be less than or equal to 100" }
]
}
},
"status": 400,
"id": "data.request_validation"
}
}Common error codes
| Status | Code | Meaning |
|---|---|---|
400 |
DATA.INVALID |
The request failed validation. data.fields lists the invalid fields. |
400 |
TRANSPORT.INVALID_PAYLOAD |
The request body could not be parsed. |
401 |
AUTH.API_KEY |
The API key is missing, invalid, deactivated or expired, or the request came from an IP address the key does not allow. |
403 |
AUTH.ACCESS |
Your partner account does not have access to this feature. |
403 |
PARTNER.SETTINGS |
This functionality is not enabled for your partner account. data.setting names the setting. |
404 |
TRANSPORT.NOT_FOUND |
No endpoint matches the method and path. |
404 |
DATA.NOT_FOUND |
The requested resource does not exist. Some resources use a more specific code, such as DATA.DOMAIN for a domain. |
Handling errors
Branch on status for the broad category, and on code — not message — for anything programmatic: messages may change, codes do not. On a 400, read data.field or data.fields to point the user at the input to fix. Retry 5xx with exponential backoff; never retry a 4xx without changing the request.
