Erros e códigos HTTP
Como a API avisa que algo deu errado e o que fazer em cada caso.
Formato
Toda resposta de erro tem o status HTTP certo e um JSON com success: false e uma message em português que você pode mostrar ou registrar. Alguns erros trazem também um code pra tratar no código.
400 Bad Requestjson
{
"success": false,
"message": "Valor mínimo: R$ 1,50"
}Códigos
| Parâmetro | Tipo | Descrição |
|---|---|---|
200 / 201 | Sucesso | A operação funcionou. 201 quando algo foi criado |
400 | Requisição inválida | Campo faltando ou fora do permitido. A message diz qual. Corrija e envie de novo |
401 | Não autenticado | “API Key inválida ou expirada” ou “Token não fornecido”. Confira o header X-API-Key |
403 | Sem permissão | Conta suspensa (code ACCOUNT_SUSPENDED), API Key sem a permissão da rota (code API_KEY_SCOPE_MISSING, edite as permissões da chave no painel), recurso desligado na sua conta ou ação que exige verificação |
404 | Não encontrado | O id não existe ou não é seu |
409 | Conflito | Algo igual já existe (por exemplo, um slug ou um cupom repetido) |
429 | Muitas requisições | Você passou do limite. Espere e tente de novo. Veja Rate Limiting |
500 / 502 / 503 | Erro do nosso lado | Falha temporária. Tente de novo em instantes e, se persistir, veja a página de status |
Boas práticas
- • Trate 5xx e 429 com nova tentativa e espera crescente. Não repita 400, 401, 403 e 404: eles não se resolvem sozinhos.
- • Em criação de cobrança ou saque, se a resposta se perdeu, consulte antes de repetir pra não duplicar.
- • Registre a
messageinteira nos seus logs: ela costuma dizer exatamente o que ajustar.
O limite de requisições está em Rate Limiting e o estado da plataforma em Status.
