Skip to main content
🤖 Judit API error responses always return a JSON object containing the root key error. Inside error, the standard keys are name (the internal error code), message (the error group), and data (an array of strings with the details or validation messages).

​
HTTP Status Codes

The API uses the standard conventions of the HTTP protocol to indicate the success or failure of a request.

​
Success (2xx)

  • 200 OK: Request processed and data returned successfully.
  • 201 Created: Resource (e.g., a new tracking) created successfully.
  • 202 Accepted: Request accepted and sent to the asynchronous processing queue.

​
Client Errors (4xx)

  • 400 Bad Request: Required parameters are missing or malformed.
  • 401 Unauthorized: The api-key header is missing, incorrect, or the key has expired.
  • 403 Forbidden: Valid key, but no permission to access that resource/endpoint.
  • 404 Not Found: The resource (e.g., lawsuit number) does not exist in the base.
  • 422 Unprocessable Entity: Data is in the correct format but not processable (e.g., mathematically invalid CNJ).
  • 429 Too Many Requests: Rate limit per minute exceeded.

​
Server Errors (5xx)

  • 500 Internal Server Error: Internal failure in the Judit API.
  • 502 Bad Gateway / 503 Service Unavailable: Temporary instability of infrastructure or of the courts.
  • 504 Gateway Timeout: The court took too long to respond to the extraction.

​
Error Structure (Payload)

Regardless of the HTTP status (whether 400 or 500), the error response body always follows this predictable JSON contract: 
{
    "error": {
        "name": "HttpBadRequestError",
        "message": "BAD_REQUEST",
        "data": [
            "CNJ is not valid",
            "Field 'area' is required"
        ]
    }
}

​
Payload Dictionary

  • name: Internal code of the exception. Use this field in your code (switch/case) for automation.
  • message: Friendly category of the error.
  • data: Array of strings containing the specific failures (very useful for displaying form validations to the end user).

​
Common Internal Codes (name)

Below are the main values that the name key can take, helping you handle the problem programmatically:

​
Authentication and Permissions

Code (name)HTTP StatusCommon Cause
USER_NOT_FOUND401API Key not sent in the header, or key revoked.
INSUFFICIENT_PERMISSIONS403Attempt to use a module that is blocked in your plan.

​
Processing and Validation

Code (name)HTTP StatusCommon Cause
HttpBadRequestError400You sent malformed JSON or missing fields.
RESOURCE_NOT_FOUND404You tried to look up a CNJ that has not yet been captured.
REQUEST_NOT_FOUND404The request_id you queried does not exist in the base.
PROCESSING_ERROR422The crawler failed to read the data at the court.

​
Code-level Handling Strategies

Best practice is to create a centralized handler (interceptor) in your application to log and handle Judit API errors. 
import requests
import os

def handle_judit_error(response: requests.Response) -> None:
    """Decodes and handles Judit API errors."""
    
    # If it's a success, do nothing
    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 failure {response.status_code}: {error_name}")
        
        # Iterating over the reasons for the error (e.g., field validations)
        if error_details:
            print("Problem details:")
            for detail in error_details:
                print(f"  - {detail}")
                
        # Decision automation based on the error type
        if error_name == 'USER_NOT_FOUND':
            raise PermissionError("Your API Key is invalid. Check your environment variables.")
            
        elif response.status_code == 429:
            print("⚠️ Rate limit exceeded. Trigger your backoff routine.")
            
    except ValueError:
        print(f"Critical error {response.status_code}: The server did not return valid JSON.")
        print(response.text)

# Example usage forcing an error (nonexistent endpoint or missing API Key)
response = requests.get(
    'https://requests.prod.judit.io/requests',
    headers={'api-key': 'wrong_key'}
)
handle_judit_error(response)

​
Next Steps

  • 👉 Rate Limits: See how to build the Retry with Exponential Backoff function to handle 429 errors.
  • 👉 Authentication: Review how to send your credentials correctly to avoid 401 errors.
  • 👉 FAQ: Read answers to the most common integration problems.