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, inconsistente com o tipo informado, ou (em `POST /customers`) dígito verificador inválido	Validar o documento — incluindo dígito verificador — 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 configurado para um `type` diferente do informado (bureau run ou cliente)	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
400	`invalid_request_error`	`customer_already_exists`	CPF/CNPJ já cadastrado para o tenant (`POST /customers`)	Consultar `GET /customers?doc=` antes de tratar como falha — ver Cliente duplicado
400	`invalid_request_error`	`external_id_conflict`	`external_id` já usado por outro cliente do tenant (`POST /customers`)	Consultar `GET /customers?external_id=` antes de tratar como falha
400	`invalid_request_error`	`missing_type`	`type` ausente ou diferente de `pf`/`pj` (`POST /customers`)	Enviar `type: "pf"` ou `type: "pj"`
400	`invalid_request_error`	`document_type_mismatch`	Quantidade de dígitos do `doc` não bate com o `type` informado (`POST /customers`)	Conferir CPF (11 dígitos) para `pf` e CNPJ (14) para `pj`
400	`invalid_request_error`	`missing_name`	`name` ausente ou fora de 2–300 caracteres (`POST /customers`)	Ajustar o tamanho de `name`
400	`invalid_request_error`	`invalid_email`	`email` ausente ou inválido — obrigatório só para `type: "pf"` (`POST /customers`)	Enviar um e-mail válido para clientes PF
400	`invalid_request_error`	`invalid_birth_date`	`birth_date` enviado para PJ, ou fora do formato `YYYY-MM-DD` (`POST /customers`)	Enviar só para PF, no formato correto
400	`invalid_request_error`	`invalid_address`	Subcampo de `address` fora das regras de tamanho/formato (`POST /customers`)	Ver regras em Campo `address`
400	`invalid_request_error`	`invalid_<campo>`	Campo complementar (`nationality`, `occupation`, `declared_income`, `trade_name`, `annual_revenue`, `business_activity`, `employee_count`) exclusivo do `type` errado, vazio ou fora do tamanho (`POST /customers`)	Ver Campos complementares
400	`invalid_request_error`	`invalid_external_id`	`external_id` com mais de 255 caracteres (`POST /customers`)	Reduzir o tamanho do identificador
400	`invalid_request_error`	`missing_default_template`	`run_bureau: true` sem `template_id` e sem template padrão configurado para o `type` do cliente	Configurar template padrão em Configurações → Bureau, ou enviar `template_id`
400	`invalid_request_error`	`invalid_date`	`created_after`/`created_before` fora do formato ISO 8601 (`GET /customers`)	Enviar data no formato ISO 8601
400	`invalid_request_error`	`invalid_id`	`{id}` da URL ausente ou inválido (`GET /customers/:id`, `POST /customers/:id/documents`)	Conferir o `customer_id` usado na URL
400	`invalid_request_error`	`invalid_multipart`	Corpo não é `multipart/form-data` válido (`POST /customers/:id/documents`, `POST /verificacoes/facial`)	Enviar como multipart, não JSON
400	`invalid_request_error`	`invalid_file`	`file` ausente ou não é um arquivo (`POST /customers/:id/documents`)	Conferir o campo `file` do multipart
400	`invalid_request_error`	`invalid_document_type`	`type` do documento ausente ou fora do catálogo aceito (`POST /customers/:id/documents`)	Ver Catálogo de `type`
400	`invalid_request_error`	`file_too_large`	Arquivo maior que 4MB (`POST /customers/:id/documents`)	Comprimir ou reduzir o arquivo antes do envio
400	`invalid_request_error`	`missing_user_image`	`user_image` ausente ou não é um arquivo (`POST /verificacoes/facial`)	Enviar `user_image` no multipart
400	`invalid_request_error`	`invalid_checks`	`checks` com valor fora de `face_match`/`passive_liveness` (`POST /verificacoes/facial`)	Ver Checks disponíveis
400	`invalid_request_error`	`missing_ref_image`	`checks` inclui `face_match` sem `ref_image` (`POST /verificacoes/facial`)	Enviar `ref_image` junto de `user_image`
400	`invalid_request_error`	`invalid_image_format`	`user_image`/`ref_image` fora de JPG/PNG/WEBP/TIFF (`POST /verificacoes/facial`)	Converter a imagem para um formato aceito
400	`invalid_request_error`	`image_too_large`	`user_image`/`ref_image` acima de 5MB (`POST /verificacoes/facial`)	Comprimir a imagem antes do envio
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
403	`authorization_error`	`channel_disabled`	Canal API desabilitado para o tenant (`POST /customers`, `POST /customers/:id/documents`, `POST /verificacoes/facial`)	Habilitar o canal API nas configurações do tenant
403	`authorization_error`	`module_disabled`	Módulo “Verificação facial” não ativo para o tenant (`POST /verificacoes/facial`)	Solicitar ativação do módulo ao compliance officer do tenant (master + configuração do tenant)
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
404	`invalid_request_error`	`customer_not_found`	`customer_id` inexistente ou de outro tenant (`GET /customers/:id`, `POST /customers/:id/documents`)	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
500	`server_error`	`storage_failed`	Falha ao gravar o arquivo no Storage (`POST /customers/:id/documents`)	Tentar novamente com backoff
500	`server_error`	`db_failed`	Falha ao ler o cliente ou registrar o documento no banco (`POST /customers/:id/documents`)	Tentar novamente com backoff
502	`server_error`	`biometric_check_failed`	Nenhum dos checks pedidos teve sucesso no provedor (`POST /verificacoes/facial`)	Tentar novamente com backoff — se persistir, contatar o suporte

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.