Pular para o conteúdo principal

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​

StatusFamíliaRepetir a mesma chamada?Atitude recomendada
400Pedido inválidoNãoCorrija o pedido
401CredencialNãoCorrija ou renove a credencial
403Permissão ou políticaNãoAjuste permissões, MFA ou o tipo de credencial
404Não encontrado ou sem acessoNãoConfira o código; lembre que casos sem acesso respondem 404
408Envio lentoSimRepita
409Conflito de estadoDependeReleia o recurso; só repita após reavaliar (exceto concurrency_conflict)
413Grande demaisNãoReduza o arquivo ou o corpo
415Codificação não aceitaNãoEnvie o corpo sem compressão
422Dados inválidosNãoCorrija os campos apontados
429Limite de taxaSim, após Retry-After (ou alguns segundos, se não vier)Espere e reduza o ritmo
500Erro internoSim, com recuoSe persistir, informe o request_id
502Serviço externo falhouSim, com recuo—
503IndisponívelSim, 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​

StatuscodeMensagemO que fazer
401unauthenticatedNão autenticado.Envie Authorization: Bearer .... Para chaves: segredo completo, chave ativa, dentro da validade e das redes permitidas. Para pessoas: renove o token.
401origin_not_allowedChaves de API não podem ser usadas a partir de um navegador.Chame a API pelo seu backend.
401invalid_credentialsE-mail ou senha inválidos.Confira as credenciais de login.
401session_revokedEsta sessão não é mais válida.Faça login de novo.
401mfa_invalidCódigo inválido.Peça um novo código ao usuário.
403permission_deniedVocê não tem permissão para esta ação.Dê à chave (ou ao papel) a permissão da rota.
403actor_not_allowedEste tipo de credencial não pode usar esta rota.A rota é exclusiva de pessoas (ou de outro tipo de credencial).
403requests_api_key_not_allowedEsta ação exige uma decisão humana e não pode ser feita por chave de API.Faça a ação no backoffice.
403mfa_challenge_requiredConfirme o segundo fator para acessar esta organização.POST /api/v1/auth/mfa/challenge.
403mfa_enrollment_requiredA organização exige um segundo fator. Cadastre um método para continuar.Cadastre um fator no backoffice.
403reporting_case_mfa_requiredPara 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.
403password_change_requiredAltere a senha temporária antes de continuar.Troque a senha no backoffice.
403recent_login_requiredPor segurança, entre de novo para continuar.Faça login novamente.
403membership_inactiveSua participação nesta organização está inativa.Fale com o administrador da organização.
403no_active_membershipVocê não possui organização ativa.—
403org_suspendedEsta organização está suspensa.Fale com o titular da organização.

Listagens e formato do pedido​

StatuscodeMensagemO que fazer
400listing_invalidFiltro, ordenação ou paginação inválidos.Confira campos e operadores permitidos; recomece sem cursor se mudou a ordenação.
400validation_errorDados inválidos.Confira o formato (por exemplo, um código público com 4 caracteres no caminho).
400requests_idempotency_header_not_supportedO cabeçalho Idempotency-Key não é aceito nas rotas de solicitações. Use request_nonce.Remova o cabeçalho e use request_nonce.
400reporting_idempotency_header_not_supportedO cabeçalho Idempotency-Key não é aceito nesta operação…Remova o cabeçalho.
400request_body_invalidCabeçalho Content-Length inválido.Corrija o cliente HTTP.
408request_body_timeoutA requisição demorou demais para ser enviada. Tente novamente.Repita.
413request_body_too_largeA requisição excede o tamanho máximo permitido.Reduza o corpo.
415request_body_encoding_unsupportedCodificaçã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)​

StatuscodeMensagemO que fazer
404requests_demand_not_foundDemanda não encontrada.O caso não existe ou a credencial não pode vê-lo (por exemplo, caso protegido).
404not_foundRecurso não encontrado.Código público inexistente na organização.
404requests_resource_unavailableO módulo de solicitações não está disponível nesta organização.—
409requests_version_conflictA 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.
409requests_nonce_conflictEste pedido já foi enviado com outro conteúdo. Atualize a tela antes de repetir.Gere um novo nonce para a nova intenção.
409requests_nonce_expiredEste pedido é antigo demais para ser repetido. Consulte o estado atual.Leia o caso e decida de novo.
409requests_transition_invalidEsta 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.
409requests_requirements_pendingAinda há dados, decisões, atividades ou entregas obrigatórias pendentes para esta ação.Veja impediments e required_fields.
409requests_demand_closedEsta manifestação já foi encerrada e não recebe novas mensagens.O caso já está encerrado; a operação não se aplica mais.
409requests_impededEsta 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).
409requests_attachment_quarantinedEste arquivo está em verificação de segurança e ainda não pode ser aberto.Tente mais tarde.
409requests_limit_exceededO limite de itens configuráveis desta organização foi atingido.Em anexos: no máximo 100 por caso.
409requests_form_version_changedO formulário deste tipo de solicitação mudou. Revise os dados e envie de novo.Releia o formulário e reenvie.
409reporting_analysis_incompleteA análise ainda não sustenta este encerramento…A equipe completa a análise no backoffice.
409reporting_analysis_outcome_mismatchO resultado escolhido não corresponde às conclusões das alegações registradas na análise.Escolha o encerramento coerente com a análise.
413requests_upload_too_largeO arquivo ultrapassa o tamanho permitido (10 MiB por arquivo).Reduza o arquivo.
422requests_validation_errorAlguns dados informados não são válidos. Revise os campos e tente de novo.Veja a lista problems.
422requests_assignee_ineligibleA pessoa indicada não pode assumir esta demanda.Use assignee-candidates.
422requests_file_type_invalidFormato de arquivo não aceito. Envie PDF, JPEG ou PNG.Converta o arquivo.
503requests_setup_pendingO catálogo de solicitações desta organização está sendo preparado…Tente após Retry-After.

Chaves, webhooks e cadastros​

StatuscodeMensagemO que fazer
400api_key_forbidden_permissionA chave não pode receber esta permissão.Remova a permissão da lista.
400event_kind_unknownEste tipo de evento não está no catálogo.Consulte GET /api/v1/webhooks/event-kinds.
400webhook_url_invalidInforme uma URL http(s) válida para o webhook.—
400webhook_url_insecureEm produção o webhook precisa ser HTTPS.Use HTTPS.
400webhook_kinds_invalidEscolha de 1 a 20 eventos do catálogo da organização.—
409webhook_delivery_stateSó uma entrega que falhou pode ser reenviada.—
400cnpj_invalidEste CNPJ não confere. Informe 14 caracteres válidos.—
404registry_not_foundNão encontramos esta empresa na Receita Federal.Preencha os dados manualmente.
503registry_unavailableA consulta à Receita está indisponível no momento…Tente de novo.
400tag_limit_exceededCada registro admite no máximo 20 etiquetas.—
409conflictJá existe um registro com esses dados.Busque o registro existente.
409idempotency_conflictA mesma chave de idempotência foi reutilizada com outro conteúdo.Use uma nova Idempotency-Key.

Temporários e de infraestrutura​

StatuscodeMensagemO que fazer
409concurrency_conflictOutra operação alterou estes dados ao mesmo tempo. Tente de novo.Repita após Retry-After (1 s).
429rate_limitedMuitas 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.
500internal_errorErro interno. Tente novamente.Repita com recuo; informe o request_id se persistir.
503unavailableServiç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:

  1. o request_id (do corpo ou do cabeçalho X-Request-ID);
  2. o método e o caminho chamados (sem o segredo da chave);
  3. o horário aproximado, com fuso;
  4. o code recebido.

Nunca envie o segredo da chave de API ao suporte. O Prefixo é suficiente para identificá-la.