Error format

Every API error uses the same envelope, and it is nested.

json

{
  "error": {
    "message": "Invalid API key.",
    "statusCode": 401,
    "code": "INVALID_API_KEY"
  }
}

Read body.error.message, never body.message.

code decides, message explains

Wire your code behaviour to the code field: it is stable and part of the contract. message is human-facing text and can be rewritten at any time, without notice.

message always comes in English, regardless of the language of this page. One more reason to branch on code.

Validation error

A contract 400 — and only that — carries validation[], pointing at the offending field:

json

{
  "error": {
    "message": "Invalid request.",
    "statusCode": 400,
    "code": "VALIDATION_ERROR",
    "validation": [
      { "field": "from", "message": "The window cannot exceed 90 days" }
    ]
  }
}

An empty list is not an error

A 200 with an empty list means there were no sales in the period, or the filter matched nothing. An integration that treats that as a failure raises a false alarm.