Erros e limites

404 no_data_found

{
  "statusCode": 404,
  "message": "CNH não encontrada para o documento informado.",
  "code": "no_data_found",
  "requestId": "9f1c2b7e-4d3a-4f8b-a6e2-1c0d9e8f7a65",
  "timestamp": "2026-10-31T14:02:11.000Z",
  "path": "/api/v1/consultas/cnh"
}

Decida pelo code, nunca pela message: ela pode mudar de redação sem aviso. Nos erros de validação (400 de corpo ou parâmetro), a message é a lista de problemas, com o campo e o motivo; nos demais, é uma string.

Catálogo de codes

Status	`code`	Quando	O que fazer
`400`	`invalid_request`	Corpo, parâmetro ou JSON inválido.	Corrigir a requisição; a `message` diz o campo.
`401`	`invalid_api_key`	Chave ausente ou que não pertence a nenhuma conta.	Conferir o header `x-api-key`.
`403`	`inactive_client`	A chave é de uma conta inativa ou ainda pendente.	Falar com o time Jusfy.
`403`	`insufficient_scope`	A chave não tem o escopo do produto; a `message` traz o escopo.	Pedir a liberação do produto ao time Jusfy.
`404`	`route_not_found`	A rota não existe.	Conferir método e path.
`404`	`resource_not_found`	O protocolo ou id não existe, ou é de outra conta (os dois respondem igual).	Conferir o id.
`404`	`no_data_found`	A consulta rodou e o documento não tem dado. É cobrada.	Tratar como resultado vazio; repetir não muda o resultado.
`409`	`report_not_ready`	O PDF do relatório ainda está em geração, ou a geração falhou.	Baixar quando estiver `done`; em `error`, pedir de novo.
`413`	`payload_too_large`	Corpo da requisição acima do limite.	Reduzir o corpo.
`422`	`payload_rejected`	O motor de cálculo ou o fornecedor recusou o payload; a `message` diz o motivo.	Corrigir o payload.
`429`	`rate_limit_exceeded`	Limite de requisições por minuto do produto excedido.	Esperar o `Retry-After`.
`429`	`too_many_pending_queries`	Consultas assíncronas demais em processamento para a conta.	Esperar o `Retry-After` — é uma estimativa: a vaga abre quando uma termina.
`500`	`internal_error`	Erro inesperado nesta API.	Repetir depois; se persistir, falar com o time Jusfy.
`502`	`upstream_error`	O motor de cálculo ou o fornecedor falhou.	Ver a orientação de cada rota: nem sempre repetir resolve.
`503`	`upstream_unavailable`	O fornecedor (ex.: o órgão consultado) está fora do ar; a consulta não rodou.	Repetir depois de um intervalo.
`504`	`upstream_timeout`	O motor de cálculo ou o fornecedor não respondeu a tempo.	Repetir depois de um intervalo.

Códigos novos podem surgir para condições que hoje não são tratadas: trate um code desconhecido pelo status. Um code existente nunca muda de significado na mesma versão.

Limite de requisições

Cada conta tem um limite por minuto em cada produto (calculadora, consulta ou JusScore); os produtos não dividem o limite entre si. A consulta do consumo tem um contador próprio. Acima do limite a resposta é 429 com o header Retry-After (segundos até poder tentar de novo), e a requisição não é processada nem cobrada.

Header	Significado
`X-RateLimit-Limit`	Requisições permitidas por minuto neste produto.
`X-RateLimit-Remaining`	Quantas ainda cabem na janela atual.
`X-RateLimit-Reset`	Segundos até a janela atual acabar.

Request ID

Toda resposta, de sucesso ou de erro, traz o header X-Request-Id, e todo erro traz o mesmo valor em requestId. Envie o seu próprio X-Request-Id (até 128 caracteres: letras, dígitos e ., _, :, -) para rastrear a chamada nos seus logs — ele é reaproveitado; sem ele, geramos um.

Ao falar com o suporte sobre uma chamada específica, informe o requestId.

Comece aqui

Fundamentos

Produtos

Referência

Catálogo de codes

Limite de requisições

Request ID

​Catálogo de codes

​Limite de requisições

​Request ID

Catálogo de codes

Limite de requisições

Request ID