Pular para o conteúdo principal

Erros

A API pública usa status HTTP + envelope:

Um contrato previsível de erros permite que sua integração resolva falhas recuperáveis automaticamente, encaminhe exceções com contexto e evite que a equipe precise investigar cada ocorrência manualmente.

Ganho operacional​

  • diferencie entrada inválida, credencial, saldo, limite e indisponibilidade;
  • aplique retry apenas quando a falha for recuperável;
  • use requestId para reduzir o tempo de diagnóstico e suporte;
  • transforme erros esperados em mensagens e ações claras no seu produto.
{
  "error": {
    "code": "CODIGO",
    "message": "Descrição legível"
  }
}

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

Tabela principal​

HTTPCódigoSignificadoComo resolver
202—Consulta ainda em processamentoNão trate como erro; siga Location/data.statusUrl e respeite Retry-After
401API_KEY_REQUIREDChave ausenteEnvie x-api-key ou Authorization: Bearer
401INVALID_API_KEYChave inválida/revogadaGere ou copie a chave em API Keys
401INVALID_DOWNLOAD_TOKENLink assinado inválido ou alteradoUse exatamente o downloadUrl retornado pela listagem autenticada
401DOWNLOAD_TOKEN_EXPIREDLink de documento expiradoConsulte documentos-publicos novamente para gerar outro link
403ACCOUNT_INACTIVEConta inativaContate o suporte
403EMAIL_VERIFICATION_REQUIREDE-mail não confirmadoConclua a verificação de cadastro
403INSUFFICIENT_CREDITSSaldo insuficienteRecarregue em Recarga
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
404—Recurso/lista vaziaTrate conforme o endpoint (ex.: processos não encontrados)
409DOWNLOAD_ALREADY_IN_PROGRESSO mesmo link já iniciou um downloadAguarde a conclusão antes de tentar novamente
410DOWNLOAD_TOKEN_ALREADY_FAILEDA tentativa vinculada ao link falhou e foi estornadaConsulte documentos-publicos novamente para gerar outro link
429—Rate limitRespeite Retry-After, X-RateLimit-*
502UPSTREAM_UNAVAILABLEFonte indisponívelRetente com backoff
422INVALID_CPF / MISSING_QUERYCPF inválido ou consulta de mandados sem CPF/peçaEnvie um CPF válido ou numero_peca
502BNMP_UNAVAILABLE / BNMP_BLOCKEDFonte de mandados temporariamente indisponívelRetente com backoff
429BNMP_RATE_LIMITEDA fonte de mandados limitou temporariamente as consultasRespeite Retry-After
500INTERNAL_ERRORErro internoPersist requestId e contate suporte

📘 Saldo insuficiente
Trate saldo insuficiente como HTTP 403 com código INSUFFICIENT_CREDITS.

HTTP 202 não é erro​

A API possui uma janela total de resposta de até 30 segundos. Se uma consulta elegível não puder terminar com segurança nessa janela, o servidor continua o mesmo trabalho em segundo plano e responde 202 Accepted antes do timeout.

  • persista data.requestId;
  • siga o header Location ou data.statusUrl com a mesma API key;
  • aguarde Retry-After, data.pollAfterSeconds ou data.pollAfterMs; data.nextPollAt informa o horário recomendado da próxima tentativa;
  • mantenha polling finito enquanto o status for 202;
  • trate o primeiro status diferente de 202 como a resposta final;
  • não repita a chamada de negócio nem crie outro job.

O estado pendente informa meta.creditsCharged: 0. A operação é cobrada uma única vez quando executada; consultar a statusUrl não executa nem cobra a operação novamente. A URL de acompanhamento é temporária e pode retornar 404 ASYNC_REQUEST_NOT_FOUND depois de expirar.

Downloads feitos por downloadUrl assinado permanecem na mesma conexão do navegador e não retornam 202. Se o link expirar ou a tentativa anterior falhar, gere outro pela listagem autenticada de documentos públicos.

Rate limit (429)​

Em rotas que usam o perfil de consulta paga a fontes judiciais:

  • limite padrão: 2 requisições por segundo por API Key, com rajada de até 10 requisições
  • resposta pode incluir retryAfter
  • headers: Retry-After, X-RateLimit-Limit, X-RateLimit-Burst, X-RateLimit-Remaining, X-RateLimit-Reset

Como tratar no cliente​

async function callApi(path: string) {
  let url = `https://api.buscaprocessos.app.br${path}`;

  for (let attempt = 0; attempt < 60; attempt += 1) {
    const res = await fetch(url, {
      headers: { "x-api-key": process.env.BUSCAPROCESSOS_API_KEY! },
    });

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

    if (res.status === 202) {
      const retryAfterMs =
        Number(res.headers.get("Retry-After") || 0) * 1000 ||
        body?.data?.pollAfterMs ||
        5000;
      url = res.headers.get("Location") || body?.data?.statusUrl;
      if (!url) throw new Error("202 sem statusUrl");
      await new Promise((resolve) => setTimeout(resolve, retryAfterMs));
      continue;
    }

    if (res.status === 429) {
      const retryAfter = Number(res.headers.get("Retry-After") || 1);
      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;
  }

  throw new Error("Limite de polling excedido");
}

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​