Códigos de Erro — Judit API - JUDIT

🤖 Esta página é a referência única de erros da Judit API: HTTP 2xx/4xx/5xx, exceções internas (name), application_error retornados no payload (mesmo quando o HTTP é 200), e troubleshooting prático.

Anatomia de um erro

A Judit API distingue dois tipos de erro:

Erros de transporte (HTTP 4xx/5xx)

A requisição falhou em validação básica, autenticação, autorização ou no servidor. O payload tem o formato { error: { name, message, data } }.

Erros de aplicação (response_type: application_error)

O HTTP é 200, mas a consulta não trouxe o objeto esperado. Pode ser “processo não encontrado”, “homônimo”, sigilo, etc. Vem dentro de responses[].response_type = application_error.

Códigos HTTP de Status

A API utiliza as convenções padrão do protocolo HTTP.

Sucesso (2xx)

HTTP	Significado	Quando ocorre
`200`	OK	Requisição processada e dados retornados com sucesso.
`201`	Created	Recurso (ex.: novo monitoramento, nova request) criado com sucesso.
`202`	Accepted	Requisição aceita e enviada para a fila de processamento assíncrono.

Erros do Cliente (4xx)

HTTP	`error.message` típico	Quando ocorre	Como resolver
`400`	`BAD_REQUEST`	Payload mal formado, campos obrigatórios ausentes, enum inválido.	Veja `error.data` — traz a lista de validações falhas. Confira o Schema do Lawsuit.
`401`	`UNAUTHORIZED`	`api-key` ausente ou inválida.	Confira o header `api-key` (sem espaço, sem `Bearer`). Ver Autenticação.
`403`	`FORBIDDEN`	A `api-key` é válida, mas não tem permissão para o recurso (ex.: feature não contratada, sigilo sem credencial).	Verifique se a feature está habilitada no seu plano e se há credencial do tribunal no Cofre.
`404`	`NOT_FOUND`	Recurso inexistente — `request_id`/`tracking_id` inválido, CNJ não está no datalake.	Confirme o ID. Para CNJs novos, dispare antes uma consulta assíncrona via `POST /requests`.
`409`	`CONFLICT`	Tracking já existente para o mesmo CNJ + chave; tentativa de criar recurso duplicado.	Liste os trackings existentes via `GET /tracking`. Atualize o existente em vez de recriar.
`422`	`UNPROCESSABLE_ENTITY`	Estrutura válida mas semanticamente inválida (ex.: `search_type` incompatível com `response_type`).	Veja a tabela em Tipos de Busca.
`429`	`TOO_MANY_REQUESTS`	Rate limit do plano excedido.	Implemente backoff exponencial. Cheque os headers `X-RateLimit-*` no response.

Erros do Servidor (5xx)

HTTP	`error.message` típico	Quando ocorre	Como resolver
`500`	`INTERNAL_SERVER_ERROR`	Falha inesperada do lado da Judit.	Tente novamente com backoff. Se persistir, abra um chamado em `support@judit.io` referenciando o `request_id`.
`502` / `504`	`BAD_GATEWAY` / `GATEWAY_TIMEOUT`	Tribunal de origem fora do ar ou timeout. Comum em consultas síncronas.	Tente novamente — se a falha persistir, fluxo assíncrono via `POST /requests` é mais resiliente.
`503`	`SERVICE_UNAVAILABLE`	Manutenção.	Aguarde alguns minutos. Acompanhe em status.judit.io (se habilitado).

Estrutura do payload de erro HTTP

Independentemente do status (400 ou 500), o corpo da resposta sempre seguirá este contrato:

{
    "error": {
        "name": "HttpBadRequestError",
        "message": "BAD_REQUEST",
        "data": [
            {
                "field": "search.search_key",
                "rule": "required",
                "message": "search_key is required"
            }
        ]
    }
}

Campo	Descrição
`error.name`	Código interno da exceção (ex.: `HttpBadRequestError`, `HttpNotFoundError`, `HttpUnauthorizedError`, `USER_NOT_FOUND`). Use no seu `switch`/`case` para automação.
`error.message`	Categoria amigável (`BAD_REQUEST`, `UNAUTHORIZED`, etc.).
`error.data`	Detalhes — array de validações ou string com mensagem específica. Útil para exibir validações de formulário ao usuário final.

Códigos internos (`error.name`)

Use estes valores para automação programática:

Autenticação e permissões

Código (`name`)	HTTP	Causa comum
`USER_NOT_FOUND`	401	API key não enviada no header ou chave revogada.
`INSUFFICIENT_PERMISSIONS`	403	Tentativa de uso de módulo bloqueado no plano.
`HttpUnauthorizedError`	401	Genérico — chave inválida.

Validação e processamento

Código (`name`)	HTTP	Causa comum
`HttpBadRequestError`	400	JSON malformado ou campos faltando.
`RESOURCE_NOT_FOUND`	404	CNJ ainda não capturado.
`REQUEST_NOT_FOUND`	404	`request_id` consultado não existe.
`PROCESSING_ERROR`	422	Robô falhou ao ler dados no tribunal.

Erros de aplicação (`application_error`)

Quando você recebe response_type: application_error em vez do payload esperado, a consulta foi processada com sucesso mas o resultado é uma exceção lógica.

`response_data.code`	Significado	Quando ocorre	Como resolver
`LAWSUIT_NOT_FOUND`	Processo não encontrado.	CNJ inexistente ou não acessível.	Verifique o número e tribunal. Pode ser sigiloso — adicione `customer_key` (Cofre).
`ENTITY_NOT_FOUND`	Pessoa/empresa não localizada.	CPF/CNPJ não consta no datalake nem no tribunal.	Tente `on_demand: true` para forçar coleta no tribunal.
`WARRANT_NOT_FOUND`	Mandado não encontrado no BNMP.	Sem mandados para o documento informado.	Tente busca por `name` ou `rji` se aplicável.
`EXECUTION_NOT_FOUND`	Execução penal não encontrada.	Sem registros para o documento.	Confira o tribunal de origem (Justiça da Execução Penal).
`INVALID_CREDENTIAL`	Credencial do Cofre inválida ou expirada.	Token/login do tribunal expirou.	Atualize a credencial no Cofre.
`CRAWLER_ERROR`	Falha na coleta do tribunal.	Tribunal fora do ar, captcha mal resolvido, mudança de layout.	Tente novamente. Se persistir, fluxo de fallback automático é acionado.
`RATE_LIMIT_TRIBUNAL`	Tribunal limitou a coleta.	Limite imposto pelo próprio tribunal.	A Judit retoma automaticamente no próximo ciclo. Use `cache_ttl_in_days` maior.
`SECRECY_RESTRICTED`	Processo em sigilo sem credencial associada.	`secrecy_level > 0` e a `api-key` não tem credencial do tribunal.	Cadastre uma credencial no Cofre e referencie via `customer_key`.
`HOMONYM_AMBIGUOUS`	Busca por nome resultou em homônimos.	Nome muito comum, sem critério adicional.	Refine via CPF/CNPJ ou aplique filtros (`tribunals`, `state`).

Exemplo de application_error

{
    "request_id": "87d9f7bf-0071-41ee-a721-e6e1b4082bc9",
    "responses": [
        {
            "response_id": "b6c1a4f0-1234-5678-9abc-def012345678",
            "response_type": "application_error",
            "response_data": {
                "code": "LAWSUIT_NOT_FOUND",
                "message": "Lawsuit 0000000-00.0000.0.00.0000 not found in datalake or court."
            }
        }
    ]
}

Handler centralizado (código pronto)

Crie um interceptador único para logar e tratar os erros da Judit API.

import requests, os

def handle_judit_error(response: requests.Response) -> None:
    """Decodifica e trata erros da Judit API."""
    if response.status_code < 400:
        return
    try:
        payload = response.json()
        error_block = payload.get('error', {})
        error_name = error_block.get('name', 'UNKNOWN_ERROR')
        error_details = error_block.get('data', [])
        print(f"❌ HTTP {response.status_code}: {error_name}")
        if error_details:
            print("Detalhes:")
            for detail in error_details:
                print(f"  - {detail}")
        if error_name == 'USER_NOT_FOUND':
            raise PermissionError("API key inválida. Verifique JUDIT_API_KEY.")
        if response.status_code == 429:
            print("⚠️ Rate limit excedido. Acione backoff.")
    except ValueError:
        print(f"Erro crítico {response.status_code}: resposta não é JSON válido.")
        print(response.text)

Padrões de tratamento

Backoff exponencial em 429 e 5xx

Implemente retry com jitter:

import time, random
for attempt in range(5):
    resp = requests.post(url, headers=h, json=body)
    if resp.status_code < 500 and resp.status_code != 429:
        break
    sleep = (2 ** attempt) + random.random()
    time.sleep(sleep)

O header Retry-After (quando presente) deve ser respeitado.

Idempotência via `callback_id`

O webhook reentrega em caso de falha. Sempre cheque callback_id antes de processar — guarde em uma tabela (id, recebido_em). Se já existe, ignore.

Distinção `application_error` vs HTTP 4xx

Trate application_error como resultado válido da consulta (a integração está OK), enquanto HTTP 4xx indica que a chamada está errada. Logue separadamente no monitoramento.

Sigilo (`secrecy_level`)

Quando o processo é sigiloso e a api-key não tem credencial registrada para o tribunal, a Judit retorna application_error: SECRECY_RESTRICTED. Para acessar, cadastre a credencial do advogado no Cofre e referencie via customer_key na própria consulta.

Quotas e limites

Ao receber 429, leia X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset para ajustar o disparo. Para fluxos em massa, adote janela deslizante.

Tabela de troubleshooting rápida

Sintoma	Hipótese mais provável	Próximo passo
HTTP 401 sempre	Header `api-key` ausente / valor errado / espaço/quebra de linha.	`echo $JUDIT_API_KEY \| wc -c` — confira o tamanho.
HTTP 403 em rota específica	Feature não habilitada no plano.	Falar com a Judit no `support@judit.io`.
`LAWSUIT_NOT_FOUND` em CNJ existente	CNJ está em sigilo.	Ver Cofre de Credenciais.
Webhook não chega	URL não pública/HTTPS, ou retornando ≠ 2xx.	Confira em Webhook.
2 webhooks com mesmo `request_id`	Comportamento esperado — primeiro vem do cache (`cached_response: true`), segundo do tribunal.	Veja cached_response.
Tracking sem novos eventos	`recurrence` muito alta ou `notification_filters.step_terms` muito restrito.	Reduza recurrence; relaxe filtros.
Resposta vazia em `name`	Homônimo ou nome com acentos.	Buscar por CPF/CNPJ; remover acentos para teste.

Próximos passos

👉 Rate Limits — função de Retry com Exponential Backoff para tratar 429.
👉 Autenticação — como enviar credenciais corretamente para evitar 401.
👉 Webhook & Callbacks — comportamento de reentregas e idempotência.
👉 Glossário — termos técnicos referenciados

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento

Dados Cadastrais

Consultas Penais

Transferência de Arquivos

Cofre de Credenciais

Webhook

Recursos

Códigos de Erro — Judit API

Anatomia de um erro

Erros de transporte (HTTP 4xx/5xx)

Erros de aplicação (response_type: application_error)

Códigos HTTP de Status

Sucesso (2xx)

Erros do Cliente (4xx)

Erros do Servidor (5xx)

Estrutura do payload de erro HTTP

Códigos internos (`error.name`)

Autenticação e permissões

Validação e processamento

Erros de aplicação (`application_error`)

Exemplo de application_error

Handler centralizado (código pronto)

Padrões de tratamento

Tabela de troubleshooting rápida

Próximos passos

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento

Dados Cadastrais

Consultas Penais

Transferência de Arquivos

Cofre de Credenciais

Webhook

Recursos

Documentation Index

​Anatomia de um erro

Erros de transporte (HTTP 4xx/5xx)

Erros de aplicação (response_type: application_error)

​Códigos HTTP de Status

​Sucesso (2xx)

​Erros do Cliente (4xx)

​Erros do Servidor (5xx)

​Estrutura do payload de erro HTTP

​Códigos internos (error.name)

​Autenticação e permissões

​Validação e processamento

​Erros de aplicação (application_error)

​Exemplo de application_error

​Handler centralizado (código pronto)

​Padrões de tratamento

​Tabela de troubleshooting rápida

​Próximos passos

Anatomia de um erro

Códigos HTTP de Status

Sucesso (2xx)

Erros do Cliente (4xx)

Erros do Servidor (5xx)

Estrutura do payload de erro HTTP

Códigos internos (`error.name`)

Autenticação e permissões

Validação e processamento

Erros de aplicação (`application_error`)

Exemplo de application_error

Handler centralizado (código pronto)

Padrões de tratamento

Tabela de troubleshooting rápida

Próximos passos