Códigos de Erro — Judit API - JUDIT

🤖 Esta página lista os erros que a Judit API retorna nas chamadas: o erro HTTP (4xx), com o código específico em error.data, e o application_error que chega como resultado de uma consulta. Todos os exemplos são respostas reais da API.

Anatomia de um erro

A Judit API distingue dois tipos de erro:

Erro HTTP (4xx)

A chamada foi recusada: autenticação, permissão, recurso inexistente ou validação. O corpo tem o formato { "error": { "name", "message", "data" } }, e o código específico vem em error.data.

Erro de aplicação (application_error)

A chamada foi aceita, mas a consulta não trouxe o objeto esperado (por exemplo, processo não encontrado). Chega como um item com response_type: "application_error" em GET /responses e no webhook.

Formato do erro HTTP

Todo erro HTTP tem o mesmo envelope:

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

Campo	Descrição
`error.name`	Classe do erro HTTP: `HttpBadRequestError`, `HttpUnauthorizedError`, `HttpForbiddenError` ou `HttpNotFoundError`.
`error.message`	Categoria: `BAD_REQUEST`, `UNAUTHORIZED`, `FORBIDDEN` ou `NOT_FOUND`.
`error.data`	O código específico. Em `401`, `403` e `404` é uma string (ex.: `USER_NOT_FOUND`, `TRACKING_NOT_FOUND`). Em `400` é uma lista de strings, uma por regra violada (ex.: `["request_id invalid UUID"]`).

Para automação, use error.data no seu switch/case. O error.name e o error.message só dizem a categoria.

Códigos HTTP

HTTP	`error.name`	`error.message`	Quando ocorre
`400`	`HttpBadRequestError`	`BAD_REQUEST`	Corpo ou parâmetros inválidos: campo obrigatório ausente, UUID malformado, valor fora do permitido, paginação fora do limite.
`401`	`HttpUnauthorizedError`	`UNAUTHORIZED`	Header `api-key` ausente ou com chave inválida.
`403`	`HttpForbiddenError`	`FORBIDDEN`	A chave é válida, mas não tem acesso ao recurso pedido.
`404`	`HttpNotFoundError`	`NOT_FOUND`	O recurso pedido pelo ID não existe.

Uma rota que não existe (URL digitada errada) retorna 404 com corpo em texto puro (Content-Type: text/plain): Not Found. Não é JSON, então trate o caso antes de fazer o parse do corpo.

Códigos em `error.data`

Autenticação (`401`)

`error.data`	Quando ocorre	Como resolver
`MISSING_AUTHORIZATION`	O header `api-key` não foi enviado.	Envie o header `api-key` em toda chamada. Ver Autenticação.
`USER_NOT_FOUND`	O header `api-key` foi enviado, mas a chave não existe.	Confira o valor da chave (sem espaço, sem quebra de linha, sem o prefixo `Bearer`).

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

Permissão (`403`)

`error.data`	Quando ocorre	Como resolver
`UNAUTHORIZED_TO_ACCESS_THIS_TRACKED_ITEM`	`GET /tracked-item` chamado sem o filtro `tracking_id`.	Informe o `tracking_id` do monitoramento.

Recurso não encontrado (`404`)

`error.data`	Rota	Quando ocorre
`REQUEST_NOT_FOUND`	`GET /requests/{request_id}`	O `request_id` não foi encontrado.
`RESPONSE_NOT_FOUND`	`GET /responses/{response_id}`	O `response_id` não foi encontrado.
`TRACKING_NOT_FOUND`	`GET /tracking/{tracking_id}`	O `tracking_id` não foi encontrado.
`TRACKED_ITEM_NOT_FOUND`	`GET /tracked-item/{tracked_item_id}`	O item monitorado não foi encontrado.
`TRANSFER_FILE_NOT_FOUND`	`GET /transfer-file/{transfer_file_id}`	A transferência de arquivo não foi encontrada.

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

Validação (`400`)

No 400, error.data é uma lista. Cada item segue o padrão "<campo> <mensagem>", e a lista traz todas as regras violadas na mesma chamada.

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

Mensagens retornadas pela API:

Rota	`error.data`	Causa
`POST /requests`, `POST /tracking`	`search invalid input: expected object, received undefined`	O corpo não tem o objeto `search`.
`POST /requests`	`search.search_type invalid option: expected one of ...`	`search_type` fora da lista aceita. A mensagem traz os valores aceitos: `cpf`, `cnpj`, `oab`, `name`, `rji`, `lawsuit_cnj`, `lawsuit_attachment`, `execution_attachment`, `custom`.
`POST /requests`	`search invalid CPF for search_key`	`search_key` não é um CPF válido.
`POST /tracking`	`search.search_type search type not allowed`	`search_type` não aceito para monitoramento.
`POST /tracking`	`search.search_key search key not allowed`	`search_key` inválido para o `search_type` informado.
`POST /tracking/bulk`	`trackings too small: expected array to have >=1 items`	A lista `trackings` está vazia.
`POST /lawsuits/count`	`search.search_type search type not allowed`	`search_type` não aceito na contagem.
`POST /entities`	`search.search_key cPF inválido. Verifique o documento informado.`	`search_key` não é um CPF válido.
`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}`	`<campo> invalid UUID` (ex.: `request_id invalid UUID`, `origin_id invalid UUID`)	O ID na URL não é um UUID.
`GET /requests`, `GET /responses/tracking/{origin_id}`	`created_at_gte invalid input: expected date, received Date` e `created_at_lte invalid input: expected date, received Date`	Os filtros de data `created_at_gte` e `created_at_lte` são obrigatórios nessas rotas, e precisam ser datas válidas (ex.: `2026-10-01T00:00:00.000Z`).
`GET /responses`	`REQUEST_OR_ORIGIN_ID_NOT_FOUND`	Faltou informar o `request_id`.
`GET /responses`	`REQUEST_NOT_FOUND`	O `request_id` informado não foi encontrado ou não é um UUID.
`GET /responses/tracking/{origin_id}`	`REQUEST_OR_TRACKING_NOT_FOUND`	O monitoramento informado não foi encontrado.
`GET /requests`	`page too small: expected number to be >=1`	`page` menor que `1`.
`GET /requests`, `GET /tracking`	`page invalid input: expected number, received NaN`	`page` não numérico.
`GET /requests`, `GET /tracking`, `GET /tracked-item`	`page_size too small: expected number to be >=5`	`page_size` menor que `5`.
`GET /requests`, `GET /transfer-file`, `GET /responses`, `GET /tracking`	`page_size too big: expected number to be <=N`	`page_size` acima do máximo da rota: `100` em `GET /requests` e `GET /transfer-file`; `1000` em `GET /responses` e `GET /tracking`.
`GET /requests`, `GET /tracking`	`status invalid status value.`	Valor de `status` fora da lista aceita.

Em GET /responses, um request_id que não existe retorna 400 (REQUEST_NOT_FOUND dentro da lista), e não 404. Já GET /requests/{request_id} retorna 404 para o mesmo caso.

Erros de aplicação (`application_error`)

Quando a consulta é aceita mas não encontra o que foi pedido, o resultado chega como um item com response_type: "application_error" nas respostas da requisição (GET /responses), que também são entregues no webhook. O response_data tem um code numérico e uma message com o nome do erro:

`response_data.code`	`response_data.message`	Quando ocorre	Como resolver
`2`	`LAWSUIT_NOT_FOUND`	O processo pedido não foi encontrado.	Confira o número do processo e, se for o caso, o tribunal informado.

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

Os avisos application_info (fim da requisição, code: 600, e monitoramento pausado, code: 700 a 703) não são erros. Veja Eventos enviados.

Handler centralizado (código pronto)

Crie um interceptador único para logar e tratar os erros da Judit API.

import requests

def handle_judit_error(response: requests.Response) -> None:
    """Decodifica e trata erros da Judit API."""
    if response.status_code < 400:
        return
    if "application/json" not in response.headers.get("Content-Type", ""):
        # Rota inexistente: 404 com corpo em texto puro ("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("API key ausente ou inválida. Verifique o header api-key.")
    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")) {
    // Rota inexistente: 404 com corpo em texto puro ("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("API key ausente ou inválida. Verifique o header api-key.");
  }
  if (response.status === 400 && Array.isArray(data)) {
    data.forEach((violation) => console.error(`  - ${violation}`));
  }
}

Padrões de tratamento

Chaveie pelo error.data, não pelo error.name

O error.name só indica a categoria (HttpNotFoundError, por exemplo). O que diferencia um TRACKING_NOT_FOUND de um REQUEST_NOT_FOUND é o error.data.

No 400, mostre todas as violações

O error.data do 400 traz todas as regras violadas de uma vez. Exiba a lista inteira para corrigir tudo numa única tentativa.

Chaveie o application_error pela message

No application_error, use response_data.message (ex.: LAWSUIT_NOT_FOUND) para decidir o tratamento.

Distinção application_error vs HTTP 4xx

Trate application_error como resultado válido da consulta (a integração está OK), enquanto HTTP 4xx indica que a chamada está errada. Logue separadamente no monitoramento.

Idempotência via callback_id

O webhook reentrega em caso de falha. Sempre cheque callback_id antes de processar — guarde em uma tabela (id, recebido_em). Se já existe, ignore.

Tabela de troubleshooting rápida

Sintoma	Causa	Próximo passo
`401` com `MISSING_AUTHORIZATION`	Header `api-key` não enviado.	Confira o nome do header: `api-key`.
`401` com `USER_NOT_FOUND`	Chave errada, com espaço ou quebra de linha.	`echo $JUDIT_API_KEY \| wc -c` — confira o tamanho.
`400` em `GET /requests` ou `GET /responses/tracking/{origin_id}` com `created_at_gte invalid input`	Faltaram os filtros de data obrigatórios.	Envie `created_at_gte` e `created_at_lte`.
`400` com `page_size too small`	`page_size` menor que `5`.	Use `page_size` a partir de `5`, até o máximo da rota.
`404` com corpo `Not Found` em texto	URL da rota errada.	Confira o host e o caminho na Referência da API.
`application_error` com `LAWSUIT_NOT_FOUND`	O processo não foi encontrado.	Confira o número do processo.
2 webhooks com mesmo `request_id`	Comportamento esperado — primeiro vem do cache (`cached_response: true`), segundo do tribunal.	Veja cached_response.

Próximos passos

👉 Autenticação — como enviar a api-key corretamente para evitar 401.
👉 Paginação — parâmetros page e page_size.
👉 Webhook & Callbacks — eventos, reentregas e idempotência.
👉 Glossário — termos técnicos referenciados.

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento

Dados Cadastrais

Consultas Penais

Transferência de Arquivos

Cofre de Credenciais

Webhook

Recursos

Códigos de Erro — Judit API

Anatomia de um erro

Erro HTTP (4xx)

Erro de aplicação (application_error)

Formato do erro HTTP

Códigos HTTP

Códigos em `error.data`

Autenticação (`401`)

Permissão (`403`)

Recurso não encontrado (`404`)

Validação (`400`)

Erros de aplicação (`application_error`)

Handler centralizado (código pronto)

Padrões de tratamento

Tabela de troubleshooting rápida

Próximos passos

​Anatomia de um erro

Erro HTTP (4xx)

Erro de aplicação (application_error)

​Formato do erro HTTP

​Códigos HTTP

​Códigos em error.data

​Autenticação (401)

​Permissão (403)

​Recurso não encontrado (404)

​Validação (400)

​Erros de aplicação (application_error)

​Handler centralizado (código pronto)

​Padrões de tratamento

​Tabela de troubleshooting rápida

​Próximos passos

Anatomia de um erro

Formato do erro HTTP

Códigos HTTP

Códigos em `error.data`

Autenticação (`401`)

Permissão (`403`)

Recurso não encontrado (`404`)

Validação (`400`)

Erros de aplicação (`application_error`)

Handler centralizado (código pronto)

Padrões de tratamento

Tabela de troubleshooting rápida

Próximos passos