Erros e limites

O envelope de erro, o catálogo de códigos e como se comportar diante de um 429.

Todo erro responde com o mesmo envelope.

{
  "message": "E_VALIDATION_FAILURE",
  "errors": ["E_VALIDATION_FAILURE: document.number"]
}

Campo	O que é
message	o código do erro. Conjunto fechado. Ramifique por ele
errors	mensagens legíveis, para log. O texto pode mudar; o código, não

O texto nunca inclui o valor que você enviou, CPF, credencial ou detalhe de fornecedor.

Catálogo

Código	HTTP	Quando	Repetir
E_VALIDATION_FAILURE	400	corpo ou parâmetro malformado, CPF ou campo inválido	não
E_UNAUTHORIZED_ACCESS	401	chave ausente, inválida, expirada ou revogada	não
E_FORBIDDEN	403	chave válida, sem a permissão necessária	não
E_NOT_FOUND	404	na criação: fluxo fora do alcance da conta, sem versão publicada, ou integração sem fluxo padrão. Em consultar verificação e baixar imagens: verificação inexistente, de outra integração, de outra conta ou do outro ambiente	não
E_REF_ID_CONFLICT	409	mesmo ref_id, corpo diferente	não
E_UNSUPPORTED_MEDIA_TYPE	415	Content-Type não é application/json	não
E_ORIGIN_NOT_VERIFIED	422	reservado para origem de app; não alcançável pela criação atual	não
E_RATE_LIMITED	429	teto da chave ou da integração	sim, após Retry-After
E_INTERNAL_SERVER_ERROR	500	falha inesperada	sim, com backoff
E_AUDIT_UNAVAILABLE	503	auditoria indisponível	sim, com backoff

Repetir é seguro: a criação é idempotente por ref_id. Mantenha o mesmo ref_id e você recebe a verificação existente em vez de uma segunda.

O 404 na criação é de fluxo

Na criação, E_NOT_FOUND não distingue fluxo inexistente, fluxo de outra conta, fluxo sem versão publicada e integração sem fluxo padrão: a resposta não conta o que existe na conta de quem pergunta. Nenhum desses casos é de domínio autorizado.

O caminho mais curto para sair dele é mandar flow_public_id na criação. Veja quando o 404 é de fluxo.

O 404 nas leituras é de verificação

Em consultar verificação e baixar imagens, E_NOT_FOUND não distingue verificação inexistente, de outra integração, de outra conta ou do outro ambiente. A chave enxerga só as verificações da integração dela, e uma chave de sandbox não enxerga verificação de produção, e vice-versa.

401 e 403

Código	A chave	O que falta
401	inválida
403	válida	a permissão
403	qualquer	nas rotas de leitura, o IP liberado

Nas rotas de leitura, o IP é conferido antes de a chamada chegar à API. O 403 por IP não vem da API, então pode não ter o formato desta página: se o 403 não traz E_FORBIDDEN, confira o IP primeiro.

Limites de uso

A criação de verificações tem teto por chave e por integração. As rotas de leitura têm teto por chave, hoje de 500 chamadas por minuto. Não dependa do número exato: respeite o Retry-After. Passando do teto, a resposta é 429 E_RATE_LIMITED com o header Retry-After em segundos.

Repetir com backoff

async function createWithRetry(body: CreateVerification, attempt = 0): Promise<Response> {
  const response = await callLegitimuz(body);
  const isRetryable = response.status === 429 || response.status >= 500;
  if (!isRetryable || attempt >= 4) return response;

  const retryAfter = Number(response.headers.get("Retry-After"));
  const delay = Number.isFinite(retryAfter) ? retryAfter * 1000 : 2 ** attempt * 500;
  await new Promise((r) => setTimeout(r, delay + Math.random() * 250));
  return createWithRetry(body, attempt + 1);
}

Para evitar o teto: crie a verificação quando a pessoa for de fato iniciar a jornada, e reaproveite a existente repetindo o ref_id. Precisa de um teto maior? Fale com o suporte com o volume esperado.

Erros dentro da jornada

Câmera negada, captura falha, credencial expirada: esses erros acontecem no widget e chegam ao seu código pelo callback de erro. Veja tratamento de erros.