Error Codes — Judit API - JUDIT

🤖 This is the single error reference for the Judit API: HTTP 2xx/4xx/5xx codes, internal exceptions (name), application_error returned in payload (even when HTTP is 200), and practical troubleshooting.

Anatomy of an error

The Judit API distinguishes two error types:

Transport errors (HTTP 4xx/5xx)

The request failed on basic validation, authentication, authorization or server side. The payload follows { error: { name, message, data } }.

Application errors (response_type: application_error)

HTTP is 200, but the query did not return the expected object. It can be “lawsuit not found”, “homonym”, secrecy, etc. Comes inside responses[].response_type = application_error.

HTTP Status Codes

The API uses standard HTTP conventions.

Success (2xx)

HTTP	Meaning	When it happens
`200`	OK	Request processed and data returned successfully.
`201`	Created	Resource (e.g. new tracker, new request) created successfully.
`202`	Accepted	Request accepted and queued for asynchronous processing.

Client Errors (4xx)

HTTP	Typical `error.message`	When it happens	How to resolve
`400`	`BAD_REQUEST`	Malformed payload, missing required fields, invalid enum.	Check `error.data` — lists failed validations. See Lawsuit Schema.
`401`	`UNAUTHORIZED`	`api-key` missing or invalid.	Check the `api-key` header (no space, no `Bearer`). See Authentication.
`403`	`FORBIDDEN`	`api-key` is valid but lacks permission (e.g. unbought feature, secrecy without credential).	Verify the feature is enabled in your plan and that there’s a court credential in the Vault.
`404`	`NOT_FOUND`	Resource doesn’t exist — invalid `request_id`/`tracking_id`, CNJ not in datalake.	Confirm the ID. For new CNJs, fire a previous async query via `POST /requests`.
`409`	`CONFLICT`	Tracking already exists for the same CNJ + key; attempt to create duplicated resource.	List existing trackers via `GET /tracking`. Update the existing one instead of recreating.
`422`	`UNPROCESSABLE_ENTITY`	Valid structure but semantically invalid (e.g. `search_type` incompatible with `response_type`).	See the table at Search Types.
`429`	`TOO_MANY_REQUESTS`	Plan rate limit exceeded.	Implement exponential backoff. Check `X-RateLimit-*` headers in response.

Server Errors (5xx)

HTTP	Typical `error.message`	When it happens	How to resolve
`500`	`INTERNAL_SERVER_ERROR`	Unexpected Judit-side failure.	Retry with backoff. If it persists, open a ticket at `support@judit.io` referencing the `request_id`.
`502` / `504`	`BAD_GATEWAY` / `GATEWAY_TIMEOUT`	Originating court down or timeout. Common in synchronous queries.	Retry — if it persists, async flow via `POST /requests` is more resilient.
`503`	`SERVICE_UNAVAILABLE`	Maintenance.	Wait a few minutes. Watch status.judit.io (if enabled).

HTTP error payload structure

Regardless of status (400 or 500), the response body always follows this contract:

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

Field	Description
`error.name`	Exception code (e.g. `HttpBadRequestError`, `HttpNotFoundError`, `HttpUnauthorizedError`, `USER_NOT_FOUND`). Use in your `switch`/`case` for automation.
`error.message`	Friendly category (`BAD_REQUEST`, `UNAUTHORIZED`, etc.).
`error.data`	Details — array of validations or string with specific message. Useful for displaying form validations to the end user.

Internal codes (`error.name`)

Use these values for programmatic automation:

Authentication and permissions

Code (`name`)	HTTP	Common cause
`USER_NOT_FOUND`	401	API key not sent or revoked.
`INSUFFICIENT_PERMISSIONS`	403	Attempt to use a module blocked in your plan.
`HttpUnauthorizedError`	401	Generic — invalid key.

Validation and processing

Code (`name`)	HTTP	Common cause
`HttpBadRequestError`	400	Malformed JSON or missing fields.
`RESOURCE_NOT_FOUND`	404	CNJ not yet captured.
`REQUEST_NOT_FOUND`	404	Queried `request_id` does not exist.
`PROCESSING_ERROR`	422	Bot failed to read court data.

Application errors (`application_error`)

When you receive response_type: application_error instead of the expected payload, the query was successfully processed, but the result is a logical exception.

`response_data.code`	Meaning	When it happens	How to resolve
`LAWSUIT_NOT_FOUND`	Lawsuit not found.	Non-existent CNJ or inaccessible.	Verify the number and tribunal. May be under secrecy — add `customer_key` (Vault).
`ENTITY_NOT_FOUND`	Person/company not found.	CPF/CNPJ doesn’t appear in datalake or court.	Try `on_demand: true` to force court fetch.
`WARRANT_NOT_FOUND`	Warrant not found in BNMP.	No warrants for the given document.	Try `name` or `rji` search if applicable.
`EXECUTION_NOT_FOUND`	Penal execution not found.	No records for the document.	Check the originating court (Penal Execution Justice).
`INVALID_CREDENTIAL`	Vault credential invalid or expired.	Court login/token expired.	Update the credential at Vault.
`CRAWLER_ERROR`	Court collection failed.	Court down, captcha failure, layout change.	Retry. If it persists, automatic fallback flow kicks in.
`RATE_LIMIT_TRIBUNAL`	Tribunal-imposed limit.	Court blocked further collection.	Judit retries automatically next cycle. Use a higher `cache_ttl_in_days`.
`SECRECY_RESTRICTED`	Secret lawsuit without associated credential.	`secrecy_level > 0` and `api-key` has no court credential.	Register a credential at Vault and reference via `customer_key`.
`HOMONYM_AMBIGUOUS`	Name search returned homonyms.	Common name without extra criteria.	Refine via CPF/CNPJ or apply filters (`tribunals`, `state`).

application_error example

{
    "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."
            }
        }
    ]
}

Centralized handler (ready-to-use code)

Create a single interceptor to log and handle Judit API errors.

import requests, os

def handle_judit_error(response: requests.Response) -> None:
    """Decode and handle Judit API errors."""
    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("Details:")
            for detail in error_details:
                print(f"  - {detail}")
        if error_name == 'USER_NOT_FOUND':
            raise PermissionError("Invalid API key. Check JUDIT_API_KEY.")
        if response.status_code == 429:
            print("⚠️ Rate limit exceeded. Trigger backoff.")
    except ValueError:
        print(f"Critical error {response.status_code}: response is not valid JSON.")
        print(response.text)

Handling patterns

Exponential backoff on 429 and 5xx

Implement retry with 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)

The Retry-After header (when present) must be respected.

Idempotency via `callback_id`

Webhooks redeliver on failure. Always check callback_id before processing — store it in a table (id, received_at). If already present, ignore.

`application_error` vs HTTP 4xx distinction

Treat application_error as a valid query result (the integration is fine), while HTTP 4xx indicates that the call is wrong. Log them separately in monitoring.

Secrecy (`secrecy_level`)

When the lawsuit is secret and the api-key has no registered credential for the court, Judit returns application_error: SECRECY_RESTRICTED. To access, register the lawyer’s credential at Vault and reference it via customer_key in the query.

Quotas and limits

On 429, read X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset to adjust dispatching. For mass flows, adopt a sliding window.

Quick troubleshooting table

Symptom	Most likely hypothesis	Next step
HTTP 401 always	Missing `api-key` header / wrong value / space/line break.	`echo $JUDIT_API_KEY \| wc -c` — check the size.
HTTP 403 on a specific route	Feature not enabled in your plan.	Talk to Judit at `support@judit.io`.
`LAWSUIT_NOT_FOUND` for an existing CNJ	CNJ is under secrecy.	See Credentials Vault.
Webhook doesn’t arrive	URL not public/HTTPS, or returning ≠ 2xx.	See Webhook.
2 webhooks with same `request_id`	Expected behavior — first comes from cache (`cached_response: true`), second from court.	See cached_response.
Tracking with no new events	`recurrence` too high or `notification_filters.step_terms` too restrictive.	Lower recurrence; relax filters.
Empty `name` response	Homonym or accented name.	Search by CPF/CNPJ; remove accents for testing.

Next steps

👉 Rate Limits — Retry with Exponential Backoff function to handle 429.
👉 Authentication — how to send credentials correctly to avoid 401.
👉 Webhook & Callbacks — redelivery behavior and idempotency.
👉 Glossary — technical terms referenced here.
👉 FAQ — frequently asked questions.

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

Error Codes — Judit API

Anatomy of an error

Transport errors (HTTP 4xx/5xx)

Application errors (response_type: application_error)

HTTP Status Codes

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

HTTP error payload structure

Internal codes (`error.name`)

Authentication and permissions

Validation and processing

Application errors (`application_error`)

application_error example

Centralized handler (ready-to-use code)

Handling patterns

Quick troubleshooting table

Next steps

Getting Started

Core Concepts

Data Models (Schemas)

Asynchronous Requests

Synchronous Requests

Tracking

Registration Data

Criminal Records

File Transfer

Credentials Vault

Webhook

Resources

Documentation Index

​Anatomy of an error

Transport errors (HTTP 4xx/5xx)

Application errors (response_type: application_error)

​HTTP Status Codes

​Success (2xx)

​Client Errors (4xx)

​Server Errors (5xx)

​HTTP error payload structure

​Internal codes (error.name)

​Authentication and permissions

​Validation and processing

​Application errors (application_error)

​application_error example

​Centralized handler (ready-to-use code)

​Handling patterns

​Quick troubleshooting table

​Next steps

Anatomy of an error

HTTP Status Codes

Success (2xx)

Client Errors (4xx)

Server Errors (5xx)

HTTP error payload structure

Internal codes (`error.name`)

Authentication and permissions

Validation and processing

Application errors (`application_error`)

application_error example

Centralized handler (ready-to-use code)

Handling patterns

Quick troubleshooting table

Next steps