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 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	fluxo fora do alcance da conta, sem versão publicada, ou integração sem fluxo padrão	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 é sempre de fluxo

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.

401 e 403

Código	A chave	A permissão
401	inválida
403	válida	falta

Limites de uso

A criação de verificações tem teto por chave e por integração. Passando dele, 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.