Tratamento de Erros

🤖 Respostas de erro da Judit API sempre retornam um objeto JSON contendo a chave raiz error. Dentro de error, as chaves padrão são name (o código interno do erro), message (o grupo do erro) e data (um array de strings com os detalhes ou mensagens de validação).

​

Códigos de Status HTTP

​

Sucesso (2xx)

• 200 OK: Requisição processada e dados retornados com sucesso.
• 201 Created: Recurso (ex: novo monitoramento) criado com sucesso.
• 202 Accepted: Requisição aceita e enviada para a fila de processamento assíncrono.

​

Erros do Cliente (4xx)

• 400 Bad Request: Faltam parâmetros obrigatórios ou eles estão malformados.
• 401 Unauthorized: O header api-key está ausente, incorreto ou a chave expirou.
• 403 Forbidden: Chave válida, mas sem permissão de acesso àquele recurso/endpoint.
• 404 Not Found: O recurso (ex: número do processo) não existe na base.
• 422 Unprocessable Entity: Dados no formato correto, mas não processáveis (ex: CNJ inválido matematicamente).
• 429 Too Many Requests: Limite de requisições por minuto excedido (Rate Limit).

​

Erros do Servidor (5xx)

• 500 Internal Server Error: Falha interna na Judit API.
• 502 Bad Gateway / 503 Service Unavailable: Instabilidade temporária de infraestrutura ou nos tribunais.
• 504 Gateway Timeout: O tribunal demorou muito para responder à extração.

​

Estrutura (Payload) de Erro

{
    "error": {
        "name": "HttpBadRequestError",
        "message": "BAD_REQUEST",
        "data": [
            "CNJ is not valid",
            "Field 'area' is required"
        ]
    }
}

​

Dicionário do Payload

• name: Código interno da exceção. Use este campo no seu código (switch/case) para automação.
• message: Categoria amigável do erro.
• data: Array de strings contendo as falhas específicas (muito útil para exibir validações de formulário para o usuário final).

​

Códigos Internos Comuns (name)

​

Autenticação e Permissões

​

Processamento e Validação

​

Estratégias de Tratamento no Código

import requests
import os

def handle_judit_error(response: requests.Response) -> None:
    """Decodifica e trata erros da Judit API."""
    
    # Se for sucesso, não faz nada
    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"❌ Falha HTTP {response.status_code}: {error_name}")
        
        # Iterando sobre os motivos do erro (Ex: validações de campos)
        if error_details:
            print("Detalhes do problema:")
            for detail in error_details:
                print(f"  - {detail}")
                
        # Automação de decisão baseada no tipo do erro
        if error_name == 'USER_NOT_FOUND':
            raise PermissionError("Sua API Key está inválida. Verifique suas variáveis de ambiente.")
            
        elif response.status_code == 429:
            print("⚠️ Rate Limit excedido. Acione sua rotina de Backoff.")
            
    except ValueError:
        print(f"Erro Crítico {response.status_code}: O servidor não retornou um JSON válido.")
        print(response.text)

# Exemplo de uso forçando um erro (endpoint inexistente ou sem API Key)
response = requests.get(
    '[https://requests.prod.judit.io/requests](https://requests.prod.judit.io/requests)',
    headers={'api-key': 'chave_errada'}
)
handle_judit_error(response)

​

Próximos Passos

• 👉 Rate Limits: Veja como construir a função de Retry com Exponential Backoff para tratar erros 429.
• 👉 Autenticação: Revise como enviar suas credenciais corretamente para evitar erros 401.
• 👉 FAQ: Veja as respostas para os problemas de integração mais comuns.