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)

async function handleJuditError(response) {
  if (response.ok) return;
  try {
    const payload = await response.json();
    const errorBlock = payload.error || {};
    const errorName = errorBlock.name || 'UNKNOWN_ERROR';
    const errorDetails = errorBlock.data || [];
    console.error(`❌ HTTP ${response.status}: ${errorName}`);
    if (errorDetails.length > 0) {
      console.error("Details:");
      errorDetails.forEach(detail => console.error(`  - ${JSON.stringify(detail)}`));
    }
    if (errorName === 'USER_NOT_FOUND') {
      throw new Error("Invalid API key. Check JUDIT_API_KEY.");
    }
    if (response.status === 429) {
      console.warn("⚠️ Rate limit exceeded. Trigger backoff.");
    }
  } catch (e) {
    if (e.name !== 'SyntaxError') throw e;
    console.error(`Critical error ${response.status}: response is not valid JSON.`);
  }
}

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

​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