> ## Documentation Index
> Fetch the complete documentation index at: https://docs.jusfy.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros e limites

> Todo erro tem o mesmo formato, com um code estável. A message é texto para pessoas e pode mudar.

```json 404 no_data_found theme={"dark"}
{
  "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.

> [!TIP]
>
> Ao falar com o suporte sobre uma chamada específica, informe o `requestId`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.