Tratamento de erros - kycert

Formato do envelope de erro

Todos os erros seguem o mesmo formato:

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_subject",
    "message": "subject é obrigatório.",
    "param": "subject"
  }
}

Campo	Descrição
`type`	Categoria do erro
`code`	Código específico — use para lógica programática
`message`	Descrição legível em português
`param`	Campo que causou o erro (quando aplicável)

Tabela de erros

HTTP	`type`	`code`	Quando ocorre	O que fazer
400	`invalid_request_error`	`missing_subject`	`subject.doc` ou `subject.type` ausente	Verificar o body da requisição
400	`invalid_request_error`	`invalid_document`	CPF/CNPJ com quantidade de dígitos incorreta ou inconsistente com `subject.type`	Validar antes de enviar
400	`invalid_request_error`	`invalid_subject_type`	`subject.type` não é `pf` nem `pj`	Verificar o campo
400	`invalid_request_error`	`subject_type_mismatch`	Template PJ, mas `subject.type: "pf"` (ou vice-versa)	Verificar o tipo do template
400	`invalid_request_error`	`missing_template_id`	`template_id` ausente	Adicionar ao body
400	`invalid_request_error`	`invalid_json`	JSON malformado no body	Verificar o body
400	`invalid_request_error`	`invalid_metadata`	`metadata` não é objeto, tem mais de 10 chaves ou valores não-string	Garantir objeto com até 10 chaves string
400	`invalid_request_error`	`invalid_webhook_url`	`webhook_url` não é uma URL HTTPS válida	Usar URL `https://`
400	`invalid_request_error`	`invalid_cursor`	Cursor de paginação corrompido	Usar cursor retornado pelo GET /runs
400	`invalid_request_error`	`unknown_api_version`	Header `x-kycert-api-version` com valor desconhecido	Usar `2026-06-03` ou omitir o header
401	`authentication_error`	`missing_api_key`	Header `x-api-key` ausente	Adicionar o header
401	`authentication_error`	`invalid_api_key`	Key revogada, inativa ou incorreta	Verificar a key no dashboard
402	`billing_error`	`quota_exceeded`	Cota mensal de runs da chave esgotada	Aumentar `runs_limit` no dashboard ou aguardar renovação
402	`billing_error`	`billing_suspended`	Saldo insuficiente ou conta suspensa	Adicionar créditos no dashboard
403	`authorization_error`	`insufficient_scope`	Key sem o escopo necessário	Criar key com o escopo correto
403	`authorization_error`	`subject_type_not_allowed`	Key restrita a PF, mas enviou PJ (ou vice-versa)	Verificar escopos da key
404	`invalid_request_error`	`template_not_found`	`template_id` inativo, errado ou de outro tenant	Verificar o ID no dashboard
404	`invalid_request_error`	`run_not_found`	`run_id` inexistente ou de outro tenant	Verificar o ID
429	`invalid_request_error`	`rate_limit_exceeded`	Cota de runs da chave atingida	Aguardar `Retry-After` segundos
500	`server_error`	`internal_error`	Falha interna	Tentar novamente com backoff
500	`server_error`	`run_not_created`	Falha ao criar o run (erro interno)	Tentar novamente com `Idempotency-Key`
500	`server_error`	`run_failed`	Falha ao iniciar o run	Tentar novamente

Estratégia de retry para clientes da API

Para chamadas à API que falham com erros temporários, use backoff exponencial:

Status	Reintentar?	Estratégia
`429` (cota atingida)	Sim	Aguardar `Retry-After` header (em segundos)
`500`, `502`, `503`, `504`	Sim	Backoff: 1s, 2s, 4s, 8s, 16s (máx 5 tentativas)
`400`	Não	Erro de validação — corrigir o request
`401`, `403`	Não	Erro de autenticação — verificar a API key
`404`	Não	Recurso não encontrado — não tente novamente

async function callWithRetry(fn: () => Promise<Response>, maxAttempts = 5) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fn()
    if (res.ok) return res
    if (res.status === 429) {
      const wait = parseInt(res.headers.get('Retry-After') ?? '60') * 1000
      await new Promise(r => setTimeout(r, wait))
      continue
    }
    if (res.status >= 500 && attempt < maxAttempts) {
      await new Promise(r => setTimeout(r, Math.pow(2, attempt) * 1000))
      continue
    }
    throw new Error(`API error: ${res.status}`)
  }
}

Use Idempotency-Key em POST /runs para garantir que retries não criem runs duplicados. Veja Idempotência.