Erros da API
Todo erro da API traz um status HTTP e, no corpo, um code estável, uma message em português e o request_id da chamada:
{
"code": "requests_demand_not_found",
"message": "Demanda não encontrada.",
"request_id": "9a7c3e1f0b2d4c6e8f1a2b3c4d5e6f70"
}
Programe em cima do code, nunca da message: o texto pode ser melhorado com o tempo; o código não muda. A exceção são os erros de formato do corpo nas rotas da organização, que respondem 422 com a lista detail (veja Convenções).
Como reagir, por família de status
| Status | Família | Repetir a mesma chamada? | Atitude recomendada |
|---|---|---|---|
400 | Pedido inválido | Não | Corrija o pedido |
401 | Credencial | Não | Corrija ou renove a credencial |
403 | Permissão ou política | Não | Ajuste permissões, MFA ou o tipo de credencial |
404 | Não encontrado ou sem acesso | Não | Confira o código; lembre que casos sem acesso respondem 404 |
408 | Envio lento | Sim | Repita |
409 | Conflito de estado | Depende | Releia o recurso; só repita após reavaliar (exceto concurrency_conflict) |
413 | Grande demais | Não | Reduza o arquivo ou o corpo |
415 | Codificação não aceita | Não | Envie o corpo sem compressão |
422 | Dados inválidos | Não | Corrija os campos apontados |
429 | Limite de taxa | Sim, após Retry-After (ou alguns segundos, se não vier) | Espere e reduza o ritmo |
500 | Erro interno | Sim, com recuo | Se persistir, informe o request_id |
502 | Serviço externo falhou | Sim, com recuo | — |
503 | Indisponível | Sim, após Retry-After | — |
Repetir sem medo
Comandos de casos levam request_nonce: repetir com o mesmo nonce e o mesmo conteúdo nunca duplica o efeito. Veja Idempotência.
Autenticação e acesso
| Status | code | Mensagem | O que fazer |
|---|---|---|---|
| 401 | unauthenticated | Não autenticado. | Envie Authorization: Bearer .... Para chaves: segredo completo, chave ativa, dentro da validade e das redes permitidas. Para pessoas: renove o token. |
| 401 | origin_not_allowed | Chaves de API não podem ser usadas a partir de um navegador. | Chame a API pelo seu backend. |
| 401 | invalid_credentials | E-mail ou senha inválidos. | Confira as credenciais de login. |
| 401 | session_revoked | Esta sessão não é mais válida. | Faça login de novo. |
| 401 | mfa_invalid | Código inválido. | Peça um novo código ao usuário. |
| 403 | permission_denied | Você não tem permissão para esta ação. | Dê à chave (ou ao papel) a permissão da rota. |
| 403 | actor_not_allowed | Este tipo de credencial não pode usar esta rota. | A rota é exclusiva de pessoas (ou de outro tipo de credencial). |
| 403 | requests_api_key_not_allowed | Esta ação exige uma decisão humana e não pode ser feita por chave de API. | Faça a ação no backoffice. |
| 403 | mfa_challenge_required | Confirme o segundo fator para acessar esta organização. | POST /api/v1/auth/mfa/challenge. |
| 403 | mfa_enrollment_required | A organização exige um segundo fator. Cadastre um método para continuar. | Cadastre um fator no backoffice. |
| 403 | reporting_case_mfa_required | Para visualizar ou atuar em uma denúncia, habilite os 2 fatores de autenticação (2FA) na sua conta. | Habilite o segundo fator na conta da pessoa. |
| 403 | password_change_required | Altere a senha temporária antes de continuar. | Troque a senha no backoffice. |
| 403 | recent_login_required | Por segurança, entre de novo para continuar. | Faça login novamente. |
| 403 | membership_inactive | Sua participação nesta organização está inativa. | Fale com o administrador da organização. |
| 403 | no_active_membership | Você não possui organização ativa. | — |
| 403 | org_suspended | Esta organização está suspensa. | Fale com o titular da organização. |
Listagens e formato do pedido
| Status | code | Mensagem | O que fazer |
|---|---|---|---|
| 400 | listing_invalid | Filtro, ordenação ou paginação inválidos. | Confira campos e operadores permitidos; recomece sem cursor se mudou a ordenação. |
| 400 | validation_error | Dados inválidos. | Confira o formato (por exemplo, um código público com 4 caracteres no caminho). |
| 400 | requests_idempotency_header_not_supported | O cabeçalho Idempotency-Key não é aceito nas rotas de solicitações. Use request_nonce. | Remova o cabeçalho e use request_nonce. |
| 400 | reporting_idempotency_header_not_supported | O cabeçalho Idempotency-Key não é aceito nesta operação… | Remova o cabeçalho. |
| 400 | request_body_invalid | Cabeçalho Content-Length inválido. | Corrija o cliente HTTP. |
| 408 | request_body_timeout | A requisição demorou demais para ser enviada. Tente novamente. | Repita. |
| 413 | request_body_too_large | A requisição excede o tamanho máximo permitido. | Reduza o corpo. |
| 415 | request_body_encoding_unsupported | Codificação do corpo da requisição não suportada. Envie sem compressão. | Não use Content-Encoding. |
| 422 | (lista detail) | — | Campo ausente, desconhecido ou de tipo errado: corrija conforme loc. |
Casos (manifestações e fluxos)
| Status | code | Mensagem | O que fazer |
|---|---|---|---|
| 404 | requests_demand_not_found | Demanda não encontrada. | O caso não existe ou a credencial não pode vê-lo (por exemplo, caso protegido). |
| 404 | not_found | Recurso não encontrado. | Código público inexistente na organização. |
| 404 | requests_resource_unavailable | O módulo de solicitações não está disponível nesta organização. | — |
| 409 | requests_version_conflict | A configuração foi alterada por outra pessoa. Atualize a tela e tente de novo. | Releia o caso, reavalie e repita com o novo expected_version e um novo request_nonce. |
| 409 | requests_nonce_conflict | Este pedido já foi enviado com outro conteúdo. Atualize a tela antes de repetir. | Gere um novo nonce para a nova intenção. |
| 409 | requests_nonce_expired | Este pedido é antigo demais para ser repetido. Consulte o estado atual. | Leia o caso e decida de novo. |
| 409 | requests_transition_invalid | Esta ação não está disponível para a demanda no estado atual. | Consulte available-transitions. Para chaves de API, também indica uma ação não liberada para integrações no fluxo. |
| 409 | requests_requirements_pending | Ainda há dados, decisões, atividades ou entregas obrigatórias pendentes para esta ação. | Veja impediments e required_fields. |
| 409 | requests_demand_closed | Esta manifestação já foi encerrada e não recebe novas mensagens. | O caso já está encerrado; a operação não se aplica mais. |
| 409 | requests_impeded | Esta pessoa está impedida neste caso e não pode receber acesso nem responsabilidade. | Escolha outra pessoa (ao conceder acesso a um caso protegido, operação feita por pessoas). |
| 409 | requests_attachment_quarantined | Este arquivo está em verificação de segurança e ainda não pode ser aberto. | Tente mais tarde. |
| 409 | requests_limit_exceeded | O limite de itens configuráveis desta organização foi atingido. | Em anexos: no máximo 100 por caso. |
| 409 | requests_form_version_changed | O formulário deste tipo de solicitação mudou. Revise os dados e envie de novo. | Releia o formulário e reenvie. |
| 409 | reporting_analysis_incomplete | A análise ainda não sustenta este encerramento… | A equipe completa a análise no backoffice. |
| 409 | reporting_analysis_outcome_mismatch | O resultado escolhido não corresponde às conclusões das alegações registradas na análise. | Escolha o encerramento coerente com a análise. |
| 413 | requests_upload_too_large | O arquivo ultrapassa o tamanho permitido (10 MiB por arquivo). | Reduza o arquivo. |
| 422 | requests_validation_error | Alguns dados informados não são válidos. Revise os campos e tente de novo. | Veja a lista problems. |
| 422 | requests_assignee_ineligible | A pessoa indicada não pode assumir esta demanda. | Use assignee-candidates. |
| 422 | requests_file_type_invalid | Formato de arquivo não aceito. Envie PDF, JPEG ou PNG. | Converta o arquivo. |
| 503 | requests_setup_pending | O catálogo de solicitações desta organização está sendo preparado… | Tente após Retry-After. |
Chaves, webhooks e cadastros
| Status | code | Mensagem | O que fazer |
|---|---|---|---|
| 400 | api_key_forbidden_permission | A chave não pode receber esta permissão. | Remova a permissão da lista. |
| 400 | event_kind_unknown | Este tipo de evento não está no catálogo. | Consulte GET /api/v1/webhooks/event-kinds. |
| 400 | webhook_url_invalid | Informe uma URL http(s) válida para o webhook. | — |
| 400 | webhook_url_insecure | Em produção o webhook precisa ser HTTPS. | Use HTTPS. |
| 400 | webhook_kinds_invalid | Escolha de 1 a 20 eventos do catálogo da organização. | — |
| 409 | webhook_delivery_state | Só uma entrega que falhou pode ser reenviada. | — |
| 400 | cnpj_invalid | Este CNPJ não confere. Informe 14 caracteres válidos. | — |
| 404 | registry_not_found | Não encontramos esta empresa na Receita Federal. | Preencha os dados manualmente. |
| 503 | registry_unavailable | A consulta à Receita está indisponível no momento… | Tente de novo. |
| 400 | tag_limit_exceeded | Cada registro admite no máximo 20 etiquetas. | — |
| 409 | conflict | Já existe um registro com esses dados. | Busque o registro existente. |
| 409 | idempotency_conflict | A mesma chave de idempotência foi reutilizada com outro conteúdo. | Use uma nova Idempotency-Key. |
Temporários e de infraestrutura
| Status | code | Mensagem | O que fazer |
|---|---|---|---|
| 409 | concurrency_conflict | Outra operação alterou estes dados ao mesmo tempo. Tente de novo. | Repita após Retry-After (1 s). |
| 429 | rate_limited | Muitas tentativas. Aguarde e tente de novo. | Espere Retry-After segundos quando o cabeçalho vier; o limite por chave de API (janela de 1 minuto) responde sem ele. |
| 500 | internal_error | Erro interno. Tente novamente. | Repita com recuo; informe o request_id se persistir. |
| 503 | unavailable | Serviço temporariamente indisponível. | Repita após Retry-After. |
Exemplo de tratamento
import time, uuid, requests
RETRYABLE = {"concurrency_conflict", "rate_limited", "unavailable", "internal_error"}
class ErroDaApi(Exception):
def __init__(self, status, code, message, request_id):
super().__init__(f"{status} {code}: {message} (request_id={request_id})")
self.status, self.code, self.request_id = status, code, request_id
class ConflitoDeVersao(Exception):
pass
def comando(session, url, body, tentativas=5):
body = {**body, "request_nonce": body.get("request_nonce") or str(uuid.uuid4())}
for n in range(tentativas):
r = session.post(url, json=body, timeout=30)
if r.ok:
return r.json()
try:
erro = r.json()
except ValueError:
erro = {}
code = erro.get("code")
if code in RETRYABLE or r.status_code in (502, 503):
espera = int(r.headers.get("Retry-After", 2 ** n))
time.sleep(espera)
continue # mesmo nonce: a repetição é segura
if code == "requests_version_conflict":
raise ConflitoDeVersao(erro) # releia o caso e decida de novo
raise ErroDaApi(r.status_code, code, erro.get("message"), erro.get("request_id"))
raise ErroDaApi(503, "unavailable", "Esgotadas as tentativas", None)
Ao abrir um chamado
Inclua sempre:
- o
request_id(do corpo ou do cabeçalhoX-Request-ID); - o método e o caminho chamados (sem o segredo da chave);
- o horário aproximado, com fuso;
- o
coderecebido.
Nunca envie o segredo da chave de API ao suporte. O Prefixo é suficiente para identificá-la.