Formato do erro

Todo erro da API tem o mesmo envelope, e ele é aninhado.

json

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

Leia body.error.message, nunca body.message.

code decide, message explica

Ligue o comportamento do seu código ao campo code: ele é estável e faz parte do contrato. A message é texto para humano e pode ser reescrita a qualquer momento, sem aviso.

A message vem sempre em inglês, independentemente do idioma desta página — é o que todo cliente de API espera. Mais uma razão para decidir pelo code.

Erro de validação

O 400 de contrato — e só ele — traz validation[], apontando o campo culpado:

json

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

Lista vazia não é erro

Resposta 200 com lista vazia significa que não houve venda no período, ou que o recorte não casou nada. Uma integração que trata isso como falha gera alarme falso.