Ferramentas
Códigos de erro
Todo erro responde com o mesmo formato. Use o codigo (estável) na lógica do seu sistema e a mensagem para exibir ou registrar.
Formato
detalhes traz informações extras: os campos inválidos em 422, a permissão que falta em 403, os valores aceitos em 400.
Resposta403 Forbidden
{
"sucesso": false,
"erro": {
"codigo": "permissao_negada",
"mensagem": "Esta chave não tem permissão 'criar' no módulo 'pagamentos'.",
"detalhes": [
{
"modulo": "pagamentos",
"permissao": "criar"
}
]
},
"request_id": "req_9a8b7c6d5e4f3a2b1c0d"
}Tabela completa
| HTTP | Código | Quando acontece | O que fazer |
|---|---|---|---|
| 401 | nao_autenticado | Header Authorization ausente ou fora do formato Bearer. | Envie Authorization: Bearer <chave> |
| 401 | chave_invalida | Chave inexistente ou incorreta. | Confira a chave copiada |
| 401 | chave_suspensa | Chave suspensa pelo administrador. | Peça reativação no painel |
| 401 | chave_revogada | Chave revogada definitivamente. | Crie uma nova chave |
| 401 | chave_expirada | Chave passou da data de expiração. | Ajuste a expiração ou crie outra |
| 403 | https_obrigatorio | Requisição feita sem HTTPS. | Use https:// |
| 403 | ip_nao_permitido | IP de origem fora da lista permitida da chave. | Cadastre o IP na chave |
| 403 | permissao_negada | A chave não tem a permissão exigida no módulo. | Libere a permissão indicada em detalhes |
| 403 | carteira_nao_permitida | A chave é restrita a outra(s) carteira(s). | Use uma chave com acesso à carteira |
| 403 | acao_indisponivel | O módulo não oferece esta ação pela API. | A operação não existe pela API para esse módulo |
| 404 | nao_encontrado | Registro não existe (ou está fora das carteiras da chave). | Confira o id e a carteira |
| 404 | rota_inexistente | Rota ou módulo desconhecido. | Confira o caminho na referência |
| 405 | metodo_nao_permitido | Método HTTP não suportado nesta rota. | Use o método indicado |
| 409 | conflito | Estado do registro impede a operação. | Releia o registro; o estado mudou |
| 409 | idempotencia_conflito | Idempotency-Key reutilizada com corpo diferente. | Use uma Idempotency-Key nova |
| 413 | corpo_muito_grande | Corpo da requisição acima do limite. | Envie até 1 MB |
| 415 | tipo_conteudo_invalido | Escrita exige Content-Type: application/json. | Envie Content-Type: application/json |
| 400 | json_invalido | Corpo não é um JSON válido. | Valide o JSON |
| 400 | parametro_invalido | Parâmetro de consulta inválido (filtro, ordenação, campos, paginação). | Corrija o parâmetro indicado |
| 422 | validacao | Um ou mais campos inválidos; ver detalhes. | Corrija os campos de detalhes |
| 429 | limite_excedido | Limite de requisições por minuto excedido. | Aguarde Retry-After |
| 500 | erro_interno | Falha inesperada; informe o request_id ao suporte. | Tente de novo; persistindo, envie o request_id ao suporte |