Skip to main content
🤖 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)

Erros do Cliente (4xx)

Erros do Servidor (5xx)

Estrutura do payload de erro HTTP

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

Códigos internos (error.name)

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

Autenticação e permissões

Validação e processamento

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.

Exemplo de application_error

Handler centralizado (código pronto)

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

Padrões de tratamento

Implemente retry com jitter:
O header Retry-After (quando presente) deve ser respeitado.
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.
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.
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.
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

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