Errors

The API uses standard HTTP status codes to signal the outcome of a request, and every error returns the same JSON envelope so you can handle failures consistently.

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 response has the same shape, with the details inside an error object:

{
  "error": {
    "code": "DATA.PRODUCT",
    "ns": "DATA",
    "message": "The specified product cannot be used",
    "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 (see below).
id	string	Optional. Present on some errors, for example data.request_validation on validation errors.

Validation errors

When a request fails validation, the API 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 is not valid JSON.
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 the HTTP status for the broad category (client error vs server error).
• Use the stable code rather than the message for programmatic decisions — messages may change, codes do not.
• On a 400, read data.field or data.fields to point the user at the input that needs fixing.
• Retry 5xx responses with exponential backoff; do not retry 4xx responses without changing the request.