Erros
O formato dos erros da API e o que fazer com cada código.
Em resumo
- Erros vêm em
application/problem+json(RFC 9457), com umcodigoestável — decida pelo código, nunca pelo texto. - Toda resposta traz
X-Request-Id. Em qualquer contato com o suporte, informe orequestId. 4xxé algo a corrigir do seu lado;5xxé do lado do Afflux — tente de novo com espera.
O formato
{
"type": "https://docs.afflux.com.br/docs/api/erros#parametro_invalido",
"title": "Parâmetro inválido",
"status": 400,
"detail": "Há parâmetros inválidos na consulta.",
"codigo": "parametro_invalido",
"requestId": "5eb85904-45ca-4043-b8d4-b58d4bb01412",
"erros": [
{ "campo": "atualizadodesde", "mensagem": "parâmetro desconhecido: atualizadodesde" }
]
}detail é escrito para quem lê o log; erros aparece nos erros de validação, campo a campo.
Os códigos
credencial_invalida
401. Chave ausente, fora do formato, desconhecida, revogada ou expirada — a resposta é a mesma em todos os casos. Confira o cabeçalho Authorization: Bearer afx_live_… e se a chave não foi revogada na tela da integração.
sem_permissao
403. A chave é válida, mas a integração não tem a permissão do recurso. O detail diz qual (por exemplo, contabancaria.ler). Peça a quem administra que conceda, se fizer sentido.
recurso_nao_contratado
403. O plano da organização não inclui esta integração — ou porque não inclui a API, ou porque há mais integrações ativas do que o plano cobre (funcionam as mais antigas). Fale com quem administra o Afflux na sua empresa.
nao_encontrado
404. O id não existe ou é de outra organização — as duas situações respondem igual. Também vale para caminho desconhecido em /api/v1 e para documento sem arquivo.
parametro_invalido
400. Parâmetro de consulta inválido ou desconhecido; erros diz qual. Parâmetro desconhecido é erro de propósito: um nome digitado errado viraria, em silêncio, uma listagem completa.
limite_por_minuto
429. Mais de 60 requisições por minuto com a mesma chave. Espere o tempo de Retry-After (em segundos).
cota_diaria_esgotada
429. A cota diária da organização acabou. Ela renova à meia-noite (horário de Brasília); Retry-After diz quanto falta. Veja Limites.
indisponivel
503. Um serviço necessário está indisponível no momento (por exemplo, ao ler dado bancário ou assinar o arquivo). Tente de novo com espera crescente.
erro_interno
500. Falha inesperada do lado do Afflux. Tente de novo com espera; se persistir, informe o requestId.
Tentar de novo
| Status | Tentar de novo? |
|---|---|
400, 401, 403, 404 | Não — corrija a chamada, a chave ou a permissão |
429 | Sim, depois do Retry-After |
500, 503 | Sim, com espera crescente (por exemplo, 1 s, 2 s, 4 s…, até alguns minutos) |
Toda chamada da API é de leitura: repetir não tem efeito colateral.