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_ORIGIN_NOT_VERIFIED",
  "errors": ["E_ORIGIN_NOT_VERIFIED: integration_origin_public_id"]
}

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 ou origem fora do alcance da conta	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	a origem ainda está aguardando validação	quando verificada
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.

401, 403 e 422

Código	A chave	A permissão	A origem
401	inválida
403	válida	falta
422	válida	tem	aguardando validação

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 criarComRetry(corpo: CriarVerificacao, tentativa = 0): Promise<Response> {
  const resposta = await chamarLegitimuz(corpo);
  const recuperavel = resposta.status === 429 || resposta.status >= 500;
  if (!recuperavel || tentativa >= 4) return resposta;

  const retryAfter = Number(resposta.headers.get("Retry-After"));
  const espera = Number.isFinite(retryAfter) ? retryAfter * 1000 : 2 ** tentativa * 500;
  await new Promise((r) => setTimeout(r, espera + Math.random() * 250));
  return criarComRetry(corpo, tentativa + 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.