Erros
Todos os erros usam o mesmo envelope JSON.
{
"error": {
"code": "invalid_request",
"message": "Filtro não suportado: foo",
"request_id": "6f3f1b7c-2f4a-4a1e-9a41-2f4d0c7e6b21"
}
}A API nunca devolve stack trace, SQL, credenciais ou detalhes internos. O
request_id também é enviado no header X-Request-Id de todas as respostas.Códigos
| Código | HTTP | Quando ocorre | Como corrigir |
|---|---|---|---|
invalid_request | 400 | Corpo, filtro ou parâmetro inválido, campo desconhecido ou fora do formato. | Ajuste o payload conforme a referência do endpoint. |
authentication_required | 401 | Header Authorization ausente. | Envie Authorization: Bearer sk_... |
invalid_api_key | 401 | Chave inexistente ou malformada. | Confira se copiou a secret completa. |
expired_api_key | 401 | A chave passou da data de expiração. | Crie ou rotacione a chave no painel. |
revoked_api_key | 401 | A chave foi revogada. | Crie uma nova chave e atualize seu ambiente. |
insufficient_scope | 403 | A chave não tem o scope exigido pelo endpoint. | Crie uma chave com o scope necessário. |
not_found | 404 | Recurso inexistente ou pertencente a outra loja. | Verifique o id enviado. |
idempotency_conflict | 409 | Mesma Idempotency-Key reutilizada com payload diferente. | Use uma chave nova para um payload diferente. |
rate_limited | 429 | Limite de requisições excedido. | Aguarde a janela reiniciar e aplique backoff. |
internal_error | 500 | Falha inesperada no processamento. | Tente novamente e informe o request_id ao suporte. |
Métodos não suportados
Endpoints somente-leitura recusam verbos de escrita com 405 e o corpo { "error": { "code": "method_not_allowed" } }. É o caso de /sales e /sales/:id.