Error Codes — Judit API - JUDIT

🤖 This page lists the errors the Judit API returns on calls: the HTTP error (4xx), with the specific code in error.data, and the application_error that arrives as a query result. All examples are real API responses.

Anatomy of an error

The Judit API distinguishes two kinds of error:

HTTP error (4xx)

The call was rejected: authentication, permission, missing resource or validation. The body has the format { "error": { "name", "message", "data" } }, and the specific code is in error.data.

Application error (application_error)

The call was accepted, but the query did not return the expected object (for example, lawsuit not found). It arrives as an item with response_type: "application_error".

HTTP error format

Every HTTP error has the same envelope:

{
  "error": {
    "name": "HttpUnauthorizedError",
    "message": "UNAUTHORIZED",
    "data": "USER_NOT_FOUND"
  }
}

Field	Description
`error.name`	HTTP error class: `HttpBadRequestError`, `HttpUnauthorizedError`, `HttpForbiddenError` or `HttpNotFoundError`.
`error.message`	Category: `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN` or `NOT_FOUND`.
`error.data`	The specific code. On `401`, `403` and `404` it is a string (e.g. `USER_NOT_FOUND`, `TRACKING_NOT_FOUND`). On `400` it is a list of strings, one per violated rule (e.g. `["request_id invalid UUID"]`).

For automation, switch on error.data. error.name and error.message only tell you the category.

HTTP codes

HTTP	`error.name`	`error.message`	When it happens
`400`	`HttpBadRequestError`	`BAD_REQUEST`	Invalid body or parameters: missing required field, malformed UUID, value not allowed, pagination out of range.
`401`	`HttpUnauthorizedError`	`UNAUTHORIZED`	`api-key` header missing or with an invalid key.
`403`	`HttpForbiddenError`	`FORBIDDEN`	The key is valid, but has no access to the requested resource.
`404`	`HttpNotFoundError`	`NOT_FOUND`	The resource requested by ID does not exist.

A route that does not exist (mistyped URL) returns 404 with a plain-text body (Content-Type: text/plain): Not Found. It is not JSON, so handle this case before parsing the body.

Codes in `error.data`

Authentication (`401`)

`error.data`	When it happens	How to fix
`MISSING_AUTHORIZATION`	The `api-key` header was not sent.	Send the `api-key` header on every call. See Authentication.
`USER_NOT_FOUND`	The `api-key` header was sent, but the key does not exist.	Check the key value (no spaces, no line breaks, no `Bearer` prefix).

{
  "error": {
    "name": "HttpUnauthorizedError",
    "message": "UNAUTHORIZED",
    "data": "MISSING_AUTHORIZATION"
  }
}

Permission (`403`)

`error.data`	When it happens	How to fix
`UNAUTHORIZED_TO_ACCESS_THIS_TRACKED_ITEM`	`GET /tracked-item` called without the `tracking_id` filter.	Send the tracking’s `tracking_id`.

Resource not found (`404`)

`error.data`	Route	When it happens
`REQUEST_NOT_FOUND`	`GET /requests/{request_id}`	The `request_id` was not found.
`RESPONSE_NOT_FOUND`	`GET /responses/{response_id}`	The `response_id` was not found.
`TRACKING_NOT_FOUND`	`GET /tracking/{tracking_id}`	The `tracking_id` was not found.
`TRACKED_ITEM_NOT_FOUND`	`GET /tracked-item/{tracked_item_id}`	The tracked item was not found.
`TRANSFER_FILE_NOT_FOUND`	`GET /transfer-file/{transfer_file_id}`	The file transfer was not found.

{
  "error": {
    "name": "HttpNotFoundError",
    "message": "NOT_FOUND",
    "data": "TRACKING_NOT_FOUND"
  }
}

Validation (`400`)

On 400, error.data is a list. Each item follows the pattern "<field> <message>", and the list includes all rules violated in the same call.

{
  "error": {
    "name": "HttpBadRequestError",
    "message": "BAD_REQUEST",
    "data": [
      "page_size too small: expected number to be >=5"
    ]
  }
}

Messages returned by the API:

Route	`error.data`	Cause
`POST /requests`, `POST /tracking`	`search invalid input: expected object, received undefined`	The body has no `search` object.
`POST /requests`	`search.search_type invalid option: expected one of ...`	`search_type` is not in the accepted list. The message lists the accepted values: `cpf`, `cnpj`, `oab`, `name`, `rji`, `lawsuit_cnj`, `lawsuit_attachment`, `execution_attachment`, `custom`.
`POST /requests`	`search invalid CPF for search_key`	`search_key` is not a valid CPF.
`POST /tracking`	`search.search_type search type not allowed`	`search_type` not accepted for trackings.
`POST /tracking`	`search.search_key search key not allowed`	`search_key` is invalid for the given `search_type`.
`POST /tracking/bulk`	`trackings too small: expected array to have >=1 items`	The `trackings` list is empty.
`POST /lawsuits/count`	`search.search_type search type not allowed`	`search_type` not accepted for counting.
`POST /entities`	`search.search_key cPF inválido. Verifique o documento informado.`	`search_key` is not a valid CPF (the message is returned in Portuguese).
`GET /requests/{request_id}`, `GET /responses/{response_id}`, `GET /responses/tracking/{origin_id}`, `GET /tracking/{tracking_id}`, `GET /tracked-item/{tracked_item_id}`, `GET /transfer-file/{transfer_file_id}`	`<field> invalid UUID` (e.g. `request_id invalid UUID`, `origin_id invalid UUID`)	The ID in the URL is not a UUID.
`GET /requests`, `GET /responses/tracking/{origin_id}`	`created_at_gte invalid input: expected date, received Date` and `created_at_lte invalid input: expected date, received Date`	The `created_at_gte` and `created_at_lte` date filters are required on these routes and must be valid dates (e.g. `2026-10-01T00:00:00.000Z`).
`GET /responses`	`REQUEST_OR_ORIGIN_ID_NOT_FOUND`	The `request_id` was not sent.
`GET /responses`	`REQUEST_NOT_FOUND`	The given `request_id` was not found or is not a UUID.
`GET /responses/tracking/{origin_id}`	`REQUEST_OR_TRACKING_NOT_FOUND`	The given tracking was not found.
`GET /requests`	`page too small: expected number to be >=1`	`page` lower than `1`.
`GET /requests`, `GET /tracking`	`page invalid input: expected number, received NaN`	`page` is not a number.
`GET /requests`, `GET /tracking`, `GET /tracked-item`	`page_size too small: expected number to be >=5`	`page_size` lower than `5`.
`GET /requests`, `GET /transfer-file`, `GET /responses`, `GET /tracking`	`page_size too big: expected number to be <=N`	`page_size` above the route’s maximum: `100` on `GET /requests` and `GET /transfer-file`; `1000` on `GET /responses` and `GET /tracking`.
`GET /requests`, `GET /tracking`	`status invalid status value.`	`status` value not in the accepted list.

On GET /responses, a request_id that does not exist returns 400 (REQUEST_NOT_FOUND inside the list), not 404. GET /requests/{request_id} returns 404 for the same case.

Application errors (`application_error`)

When the query is accepted but does not find what was requested, the result arrives as an item with response_type: "application_error" in the request’s responses (GET /responses), which are also delivered to the webhook. response_data has a numeric code and a message with the error name:

`response_data.code`	`response_data.message`	When it happens	How to fix
`2`	`LAWSUIT_NOT_FOUND`	The requested lawsuit was not found.	Check the lawsuit number and, if applicable, the court you sent.

{
  "response_type": "application_error",
  "response_data": {
    "code": 2,
    "message": "LAWSUIT_NOT_FOUND"
  }
}

application_info notices (request completed, code: 600, and tracking paused, code: 700 to 703) are not errors. See Events delivered.

Centralized handler (ready-to-use code)

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

import requests

def handle_judit_error(response: requests.Response) -> None:
    """Decodes and handles Judit API errors."""
    if response.status_code < 400:
        return
    if "application/json" not in response.headers.get("Content-Type", ""):
        # Route does not exist: 404 with a plain-text body ("Not Found")
        raise RuntimeError(f"HTTP {response.status_code}: {response.text}")
    error = response.json().get("error", {})
    data = error.get("data")
    print(f"❌ HTTP {response.status_code} {error.get('message')}: {data}")
    if data in ("MISSING_AUTHORIZATION", "USER_NOT_FOUND"):
        raise PermissionError("Missing or invalid API key. Check the api-key header.")
    if response.status_code == 400 and isinstance(data, list):
        for violation in data:
            print(f"  - {violation}")

async function handleJuditError(response) {
  if (response.ok) return;
  const contentType = response.headers.get("content-type") || "";
  if (!contentType.includes("application/json")) {
    // Route does not exist: 404 with a plain-text body ("Not Found")
    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
  const { error = {} } = await response.json();
  const data = error.data;
  console.error(`❌ HTTP ${response.status} ${error.message}: ${JSON.stringify(data)}`);
  if (data === "MISSING_AUTHORIZATION" || data === "USER_NOT_FOUND") {
    throw new Error("Missing or invalid API key. Check the api-key header.");
  }
  if (response.status === 400 && Array.isArray(data)) {
    data.forEach((violation) => console.error(`  - ${violation}`));
  }
}

Handling patterns

Switch on error.data, not error.name

error.name only tells you the category (HttpNotFoundError, for example). What distinguishes a TRACKING_NOT_FOUND from a REQUEST_NOT_FOUND is error.data.

On 400, show every violation

The 400 error.data includes every violated rule at once. Show the whole list so everything can be fixed in a single attempt.

Switch on the application_error message

For application_error, use response_data.message (e.g. LAWSUIT_NOT_FOUND) to decide how to handle it.

application_error vs HTTP 4xx

Treat application_error as a valid result of the query (the integration is OK), while HTTP 4xx means the call is wrong. Log them separately in your monitoring.

Idempotency via callback_id

The webhook redelivers on failure. Always check callback_id before processing — store it in a table (id, received_at). If it already exists, ignore it.

Quick troubleshooting table

Symptom	Cause	Next step
`401` with `MISSING_AUTHORIZATION`	`api-key` header not sent.	Check the header name: `api-key`.
`401` with `USER_NOT_FOUND`	Wrong key, or with a space or line break.	`echo $JUDIT_API_KEY \| wc -c` — check the length.
`400` on `GET /requests` or `GET /responses/tracking/{origin_id}` with `created_at_gte invalid input`	The required date filters are missing.	Send `created_at_gte` and `created_at_lte`.
`400` with `page_size too small`	`page_size` lower than `5`.	Use a `page_size` from `5` up to the route’s maximum.
`404` with a plain-text `Not Found` body	Wrong route URL.	Check the host and path in the API Reference.
`application_error` with `LAWSUIT_NOT_FOUND`	The lawsuit was not found.	Check the lawsuit number.
2 webhooks with the same `request_id`	Expected behavior — the first comes from cache (`cached_response: true`), the second from the court.	See cached_response.

Next steps

👉 Authentication — how to send the api-key correctly to avoid 401.
👉 Pagination — the page and page_size parameters.
👉 Webhook & Callbacks — events, redeliveries and idempotency.
👉 Glossary — referenced technical terms.

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

HTTP error (4xx)

Application error (application_error)

HTTP error format

HTTP codes

Codes in `error.data`

Authentication (`401`)

Permission (`403`)

Resource not found (`404`)

Validation (`400`)

Application errors (`application_error`)

Centralized handler (ready-to-use code)

Handling patterns

Quick troubleshooting table

Next steps

​Anatomy of an error

HTTP error (4xx)

Application error (application_error)

​HTTP error format

​HTTP codes

​Codes in error.data

​Authentication (401)

​Permission (403)

​Resource not found (404)

​Validation (400)

​Application errors (application_error)

​Centralized handler (ready-to-use code)

​Handling patterns

​Quick troubleshooting table

​Next steps

Anatomy of an error

HTTP error format

HTTP codes

Codes in `error.data`

Authentication (`401`)

Permission (`403`)

Resource not found (`404`)

Validation (`400`)

Application errors (`application_error`)

Centralized handler (ready-to-use code)

Handling patterns

Quick troubleshooting table

Next steps