Conceitos

Arquivos & erros

O que uma boa foto precisa ter, o que acontece quando ela não tem — e exatamente como resolver cada caso.

Especificações de imagem

Parâmetro	Requisito	Notas
Formatos	JPEG, PNG, WebP, HEIC	HEIC/WebP convertidos automaticamente — fotos de iPhone funcionam sem conversão no cliente
Lado menor	≥ 480 px	≥ 1080 px habilita análise de alta fidelidade automaticamente (mesmas dimensões, mais detalhe regional)
Lado maior	≤ 4096 px	Acima disso, redimensionamos automaticamente — sem erro
Tamanho	≤ 10 MB (multipart)	Maiores: fluxo opcional `POST /v1/uploads`
Rosto	50–90% da largura	Faixa mais tolerante que o padrão de mercado (60–80%); o Capture Kit garante isso na captura

A foto ideal

Frontal, expressão neutra, olhos abertos, câmera na altura dos olhos
Luz uniforme e clara (de frente, nunca por trás); sem contraluz de janela
Sem óculos, sem maquiagem pesada, cabelo fora da testa, sem filtros

Dica de produto: não ensine regras ao usuário — capture certo na origem. O Capture Kit valida enquadramento, pose e luz em tempo real e só libera o disparo quando a foto vai passar.

Envelope de erro

Todo erro tem o mesmo formato, com código estável, mensagem legível, dica de correção e link direto para esta documentação:

json · 422

{
  "error": {
    "code": "face_too_small",
    "message": "O rosto ocupa menos de 50% da largura da imagem.",
    "hint": "Aproxime a câmera até o rosto preencher a moldura, ou use o Capture Kit.",
    "docs_url": "https://www.nutoken.com.br/docs/arquivos-e-erros.html#face_too_small"
  }
}

Catálogo de erros

Código	HTTP	Causa	Como resolver
`invalid_image`	400	Arquivo corrompido ou formato não suportado	Reenvie em JPEG/PNG/WebP/HEIC
`image_too_small`	422	Lado menor < 480 px	Capture em resolução maior; evite thumbnails
`image_too_large`	413	> 10 MB no multipart	Comprima no cliente ou use `POST /v1/uploads`
`face_not_found`	422	Nenhum rosto detectado	Foto frontal, sem oclusões; verifique rotação EXIF
`face_too_small`	422	Rosto < 50% da largura	Aproxime a câmera
`face_out_of_bounds`	422	Rosto cortado pela borda	Centralize o rosto no enquadramento
`multiple_faces`	422	Mais de um rosto na imagem	Uma pessoa por análise
`lighting_too_dark`	422	Subexposição	Luz de frente; evite ambientes escuros
`lighting_uneven`	422	Sombra forte em metade do rosto	Luz difusa e frontal (janela de frente funciona)
`consent_missing`	422	`consent.obtained` ausente ou falso	Colete e declare o consentimento do titular
`invalid_dimensions`	400	Dimensão inexistente em `dimensions`	Confira a lista em Entradas & saídas
`idempotency_conflict`	409	Mesma `Idempotency-Key` com corpo diferente	Gere uma chave nova por operação distinta
`insufficient_units`	402	Saldo de unidades esgotado	Ver Unidades & cobrança
`rate_limited`	429	Limite de requisições excedido	Respeite `Retry-After`; aplique backoff exponencial
`processing_failed`	—	Falha interna do motor (status `failed`)	Reenvie; nenhuma unidade é consumida

Diferença que importa: erros de qualidade de foto (422) chegam na resposta síncrona da criação sempre que detectáveis de imediato — você não gasta um ciclo de polling/webhook para descobrir que a foto estava escura. No padrão do mercado, esses erros só aparecem ao consultar a task.