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.
| HTTP | Tipo | O que aconteceu e o que fazer |
|---|---|---|
400 | about:blank | Corpo que não é JSON válido ou acima do tamanho. Corrija o corpo. Não repita igual. |
401 | chave-invalida | Chave ausente, errada ou revogada. Confira o cabeçalho Authorization. |
402 | saldo-insuficiente | Pré-pago sem saldo para o preço da consulta. Recarregue no portal, em Consumo. |
403 | produto-nao-liberado | Produto fora da chave ou não contratado. Libere o produto na chave ou contrate no portal. |
403 | ip-nao-permitido | IP fora da lista de IPs permitidos da conta. Cadastre o IP em Configurações. |
404 | produto-desconhecido | O produto da URL não existe. Confira o nome do produto na URL. |
422 | cpf-invalido | CPF com dígito verificador errado. Corrija o documento. |
422 | cnpj-invalido | CNPJ com dígito verificador errado. Corrija o documento. |
422 | crm-invalido | CRM ou UF fora do formato (produto crm). Corrija o CRM e a UF. |
422 | nome-da-mae-invalido | Nome 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. |
422 | campo-invalido | Campo obrigatório faltando ou fora do formato. O detail diz qual campo e por quê. Corrija o campo citado. |
422 | dados-invalidos | referencia com mais de 80 caracteres. Encurte a referência. |
429 | muitas-requisicoes | Passou de 1.000 requisições por minuto na chave. Espere os segundos de Retry-After. |
429 | limite-do-dia | A chave atingiu o limite de gasto do dia. Espere Retry-After (até a meia-noite) ou aumente o limite no portal. |
429 | fonte-em-uso | APIs do eSocial: já há uma consulta em andamento para a mesma empresa. Espere ela terminar e repita. |
429 | limite-da-fonte | APIs 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. |
503 | fonte-ocupada | A fonte está no limite de chamadas por minuto. Nada foi cobrado. Espere Retry-After e repita. |
503 | fonte-fora-do-horario | APIs 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. |
503 | produto-indisponivel | Produto temporariamente indisponível em produção. Nada foi cobrado. Tente mais tarde; em teste, use a chave nxq_test_. |
Quando repetir uma chamada
| Resposta | Repetir? |
|---|---|
2xx | Não. Guarde o id. |
400, 401, 402, 403, 404, 422 | Não — a mesma chamada vai falhar igual. Corrija antes. |
429, 503 | Sim, depois dos segundos do cabeçalho Retry-After. |
200 com em_processamento | Não. A consulta já está na fila e é refeita sozinha; repetir cria outra consulta. Espere o webhook e busque pelo id. |
502 | Sim, com espera crescente (ex.: 1 min, 5 min, 15 min). |
| Timeout do seu lado, sem resposta | Confira no histórico do portal (pela referencia) antes de repetir: a consulta pode ter sido concluída. |