Erros

Todo erro segue a RFC 9457. O que cada um significa, o que fazer e quando repetir a chamada.

Todo erro segue a RFC 9457 — Problem Details, com Content-Type: application/problem+json:

{
  "type": "urn:nexusquery:problema:campo-invalido",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Campo uf: a Polícia Civil de SP exige este campo."
}

Decida pelo type, que é estável. detail é para pessoas e pode mudar de texto.

Todo type começa com urn:nexusquery:problema:; a tabela mostra só o final.

HTTPTipoO que aconteceu e o que fazer
400about:blankCorpo que não é JSON válido ou acima do tamanho. Corrija o corpo. Não repita igual.
401chave-invalidaChave ausente, errada ou revogada. Confira o cabeçalho Authorization.
402saldo-insuficientePré-pago sem saldo para o preço da consulta. Recarregue no portal, em Consumo.
403produto-nao-liberadoProduto fora da chave ou não contratado. Libere o produto na chave ou contrate no portal.
403ip-nao-permitidoIP fora da lista de IPs permitidos da conta. Cadastre o IP em Configurações.
404produto-desconhecidoO produto da URL não existe. Confira o nome do produto na URL.
422cpf-invalidoCPF com dígito verificador errado. Corrija o documento.
422cnpj-invalidoCNPJ com dígito verificador errado. Corrija o documento.
422crm-invalidoCRM ou UF fora do formato (produto crm). Corrija o CRM e a UF.
422nome-da-mae-invalidoNome da mãe com menos de 3 ou mais de 120 caracteres, ou com {, } ou vírgula. Envie o nome sem esses caracteres, ou não envie.
422campo-invalidoCampo obrigatório faltando ou fora do formato. O detail diz qual campo e por quê. Corrija o campo citado.
422dados-invalidosreferencia com mais de 80 caracteres. Encurte a referência.
429muitas-requisicoesPassou de 1.000 requisições por minuto na chave. Espere os segundos de Retry-After.
429limite-do-diaA chave atingiu o limite de gasto do dia. Espere Retry-After (até a meia-noite) ou aumente o limite no portal.
429fonte-em-usoAPIs do eSocial: já há uma consulta em andamento para a mesma empresa. Espere ela terminar e repita.
429limite-da-fonteAPIs do eSocial: a empresa esgotou os 10 acessos do dia no governo. Repita amanhã.
502— (resposta de consulta)A fonte não respondeu e não havia como pôr a consulta na fila: corpo normal com o desfecho (sem_retorno, indisponivel, pedido_recusado), não cobrada. Tente de novo em alguns minutos.
503fonte-ocupadaA fonte está no limite de chamadas por minuto. Nada foi cobrado. Espere Retry-After e repita.
503fonte-fora-do-horarioAPIs do eSocial entre os dias 1 e 7 de cada mês, quando o governo não atende. Nada foi cobrado. Repita a partir do dia 8.
503produto-indisponivelProduto temporariamente indisponível em produção. Nada foi cobrado. Tente mais tarde; em teste, use a chave nxq_test_.

Quando repetir uma chamada

RespostaRepetir?
2xxNão. Guarde o id.
400, 401, 402, 403, 404, 422Não — a mesma chamada vai falhar igual. Corrija antes.
429, 503Sim, depois dos segundos do cabeçalho Retry-After.
200 com em_processamentoNão. A consulta já está na fila e é refeita sozinha; repetir cria outra consulta. Espere o webhook e busque pelo id.
502Sim, com espera crescente (ex.: 1 min, 5 min, 15 min).
Timeout do seu lado, sem respostaConfira no histórico do portal (pela referencia) antes de repetir: a consulta pode ter sido concluída.