Guides
  1. Operação

Erros

A API pública usa status HTTP + envelope:

{
  "error": {
    "code": "CODIGO",
    "message": "Descrição legível"
  }
}

Alguns erros incluem campos extras (por exemplo, availableCredits e requiredCredits).

Tabela principal

HTTPCódigoSignificadoComo resolver
401API_KEY_REQUIREDChave ausenteEnvie x-api-key ou Authorization: Bearer
401INVALID_API_KEYChave inválida/revogadaGere ou copie a chave em /dashboard/keys
403ACCOUNT_INACTIVEConta inativaContate o suporte
403EMAIL_VERIFICATION_REQUIREDE-mail não confirmadoConclua a verificação de cadastro
403INSUFFICIENT_CREDITSSaldo insuficienteRecarregue em /dashboard/topup
400MISSING_DOCUMENTDocumento não informadoEnvie cpf_cnpj ou document
400MISSING_SEARCH_TERMTermo ausenteInforme o parâmetro de busca exigido
400INVALID_JSONBody JSON inválidoValide o payload
422INVALID_DOCUMENTCPF/CNPJ inválidoNormalize e valide dígitos
422INVALID_LIMITLimit inválidoEm /v1/processos, use 50 ou 100
422INVALID_CNJCNJ inválidoNormalize o número CNJ
422INVALID_OAB / INVALID_OABSOAB inválidaUse UF e número corretos
422INVALID_WEBHOOK_URLWebhook inválidoUse HTTPS válido
404INVALID_API_HOSTHost incorretoUse api.buscaprocessos.app.br
404MONITORING_NOT_FOUNDMonitoramento inexistenteConfira o ID da conta
404CERTIFICATE_NOT_FOUNDCertificado inexistenteListe certificados da conta
404—Recurso/lista vaziaTrate conforme o endpoint (ex.: processos não encontrados)
429—Rate limitRespeite Retry-After, X-RateLimit-*
502UPSTREAM_UNAVAILABLEFonte indisponívelRetente com backoff
500INTERNAL_ERRORErro internoPersist requestId e contate suporte
📘

Nota sobre 402
Alguma documentação interna do painel menciona HTTP 402 para saldo. No código da API pública, saldo insuficiente é retornado como 403 INSUFFICIENT_CREDITS.

Rate limit (429)

Em rotas que usam o perfil de consulta paga/escavador:

  • limite típico: 5 requisições / 60 segundos / IP
  • resposta pode incluir retryAfter
  • headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset

Como tratar no cliente

async function callApi(path: string) {
  const res = await fetch(`https://api.buscaprocessos.app.br${path}`, {
    headers: { "x-api-key": process.env.BUSCAPROCESSOS_API_KEY! },
  });

  const body = await res.json().catch(() => ({}));

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get("Retry-After") || 1);
    // agende retry com jitter
    throw Object.assign(new Error("rate_limited"), { retryAfter });
  }

  if (!res.ok) {
    throw Object.assign(new Error(body?.error?.message || "api_error"), {
      status: res.status,
      code: body?.error?.code,
      body,
    });
  }

  return body;
}

Correlação e suporte

Sempre registre, quando disponíveis:

  • meta.requestId
  • header X-BuscaProcessos-Request-Id
  • meta.searchLogId
  • status HTTP e error.code

Isso acelera o atendimento em WhatsApp de suporte.

Relacionados