Erros & limites

Formato de erro

Toda resposta de erro segue o mesmo envelope JSON:


{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Chave de API inválida, revogada ou expirada.",
  "code": "invalid_api_key"
}

statusCode — o código HTTP.
error — nome curto do erro.
message — mensagem legível (pt-BR).
code — código estável da aplicação, ideal para tratar no seu cliente.

Códigos comuns

Status	`code`	Quando acontece
`400`	`validation_error`	Parâmetros inválidos (veja `issues`)
`401`	`missing_api_key`	Header `Authorization` ausente
`401`	`invalid_api_key`	Chave inválida/revogada/expirada
`403`	`insufficient_scope`	Escopo insuficiente para a operação
`404`	`not_found`	Recurso não encontrado
`429`	—	Rate limit excedido
`500`	—	Erro interno

Rate limiting

As requisições são limitadas por chave de API. Ao exceder o limite, a API responde 429 Too Many Requests. Implemente retry com backoff exponencial e respeite os headers de limite quando presentes.

Paginação

Endpoints de listagem aceitam page e pageSize (máx. 100) e retornam:


{
  "data": [ /* ... */ ],
  "meta": { "page": 1, "pageSize": 20, "total": 134, "totalPages": 7 }
}