​
Códigos de Status HTTP

​
Códigos de Sucesso

  • 200 OK: Requisição processada com sucesso
  • 201 Created: Recurso criado com sucesso
  • 202 Accepted: Requisição aceita para processamento assíncrono

​
Códigos de Erro do Cliente

  • 400 Bad Request: Parâmetros inválidos ou malformados
  • 401 Unauthorized: API Key ausente ou inválida
  • 403 Forbidden: Acesso negado ao recurso
  • 404 Not Found: Recurso não encontrado
  • 409 Conflict: Conflito com estado atual do recurso
  • 422 Unprocessable Entity: Dados válidos mas não processáveis
  • 429 Too Many Requests: Rate limit excedido

​
Códigos de Erro do Servidor

  • 500 Internal Server Error: Erro interno do servidor
  • 502 Bad Gateway: Erro de gateway
  • 503 Service Unavailable: Serviço temporariamente indisponível
  • 504 Gateway Timeout: Timeout de gateway

​
Estrutura de Resposta de Erro

Todas as respostas de erro seguem um formato consistente: 
{
    "error": {
        "name": "HttpBadRequestError",
        "message": "BAD_REQUEST",
        "data": [
            "CNJ is not valid"
        ]
    }
}

​
Campos da Resposta de Erro

  • code: Código único do erro para identificação programática
  • message: Mensagem descritiva em português
  • data: Informações adicionais específicas do erro

​
Códigos de Erro Específicos

​
Autenticação e Autorização

CódigoDescriçãoStatus HTTP
USER_NOT_FOUNDAPI Key inválida ou expirada401
INSUFFICIENT_PERMISSIONSPermissões insuficientes403

​
Recursos e Processamento

CódigoDescriçãoStatus HTTP
RESOURCE_NOT_FOUNDRecurso não encontrado404
REQUEST_NOT_FOUNDRequisição não encontrada404
TRACKING_NOT_FOUNDTracking não encontrado404
PROCESSING_ERRORErro durante processamento422
TIMEOUT_ERRORTimeout na consulta ao tribunal504

​
Estratégias de Tratamento

​
1. Retry com Backoff Exponencial

import time
import random
import requests
from typing import Optional

def make_request_with_retry(
    url: str,
    headers: dict,
    max_retries: int = 3,
    base_delay: float = 1.0
) -> Optional[requests.Response]:
    """
    Faz requisição com retry e backoff exponencial
    """
    for attempt in range(max_retries + 1):
        try:
            response = requests.get(url, headers=headers, timeout=30)
            
            # Sucesso
            if response.status_code < 400:
                return response
            
            # Não fazer retry para erros do cliente (4xx)
            if 400 <= response.status_code < 500:
            
            # Retry para erros 5xx
            if attempt < max_retries:
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                print(f"Tentativa {attempt + 1} falhou. Aguardando {delay:.2f}s...")
                time.sleep(delay)
            else:
                return response
                
        except requests.exceptions.RequestException as e:
            if attempt < max_retries:
                delay = base_delay * (2 ** attempt) + random.uniform(0, 1)
                print(f"Erro de conexão. Tentativa {attempt + 1}. Aguardando {delay:.2f}s...")
                time.sleep(delay)
            else:
                raise e
    
    return None

# Uso
response = make_request_with_retry(
    'https://requests.prod.judit.io/requests',
    headers={'api-key': os.getenv('JUDIT_API_KEY')}
)

​
2. Tratamento Específico por Tipo de Erro

def handle_api_error(response: requests.Response) -> None:
    """
    Trata erros específicos da API
    """
    if response.status_code == 200:
        return
    
    try:
        error_data = response.json().get('error', {})
        error_code = error_data.get('code', 'UNKNOWN_ERROR')
        error_message = error_data.get('message', 'Erro desconhecido')
        request_id = error_data.get('request_id', 'N/A')
        
        print(f"Erro {response.status_code}: {error_message}")
        print(f"Código: {error_code}")
        print(f"Request ID: {request_id}")
        
        # Tratamento específico por código
        if error_code == 'USER_NOT_FOUND':
            print("⚠️ Verifique sua API Key")
            
        elif error_code == 'VALIDATION_ERROR':
            details = error_data.get('details', {})
            field = details.get('field', 'desconhecido')
            reason = details.get('reason', 'erro de validação')
            print(f"❌ Campo '{field}': {reason}")
            
        else:
            print(f"❓ Erro não tratado: {error_code}")
            
    except (ValueError, KeyError) as e:
        print(f"Erro ao processar resposta de erro: {e}")
        print(f"Status: {response.status_code}")
        print(f"Resposta: {response.text[:200]}...")

# Uso
response = requests.get(
    'https://requests.prod.judit.io/requests',
    headers={'api-key': os.getenv('JUDIT_API_KEY')}
)

handle_api_error(response)

​
Próximos Passos

  • Rate Limits: Entenda os limites e como evitar erros 429
  • FAQ: Perguntas frequentes sobre erros comuns
Dica: Sempre implemente logging adequado e monitore os request_id para facilitar o suporte técnico.