Ir para o conteúdo principal
Contrato OpenAPI v0.1.0: Alinhado ao arquivo contracts/openapi.yaml. Endpoints exclusivos do Console (/dashboard/v1) aguardam publicação complementar do backend.

Erros, Timeouts e Retries

A API utiliza códigos de status HTTP padrão e respostas estruturadas no formato RFC 9457 (application/problem+json).

Formato Problem Details

{
  "type": "https://conformo.com.br/docs/errors#no_face_detected",
  "title": "Nenhum rosto detectado na imagem",
  "status": 422,
  "detail": "Não foi possível localizar um rosto válido na imagem de destino.",
  "instance": "/v1/face/compare",
  "error_code": "no_face_detected",
  "request_id": "req_01J8X9P3K8",
  "operation_id": null,
  "billable": false
}

Sempre registre o campo request_id (e o header X-Request-Id) nos seus logs de backend para agilizar atendimentos de suporte.

Códigos de erro esperados

HTTP error_code Significado e ação recomendada
401 unauthorized API key ausente, inválida ou revogada.
402 insufficient_balance Saldo insuficiente. Recarregue via Pix no console.
422 no_face_detected Nenhum rosto localizado. Solicite nova foto ao usuário.
422 multiple_faces_detected Mais de um rosto na imagem. Envie foto individual.
422 insufficient_image_quality Imagem escura, borrada ou com resolução insuficiente.
429 rate_limit_exceeded Limite de taxa atingido. Respeite o header Retry-After.

Timeouts e Retries

  • Configure timeout mínimo recomendado de 15 segundos no seu cliente HTTP.
  • Faça retry com backoff exponencial + jitter apenas em erros 429, 502, 503, 504 ou timeout de rede — sempre mantendo a mesma Idempotency-Key.
  • Nunca faça retry automático em erros 400, 401, 402 ou 422 sem corrigir a entrada.