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,504ou timeout de rede — sempre mantendo a mesmaIdempotency-Key. - Nunca faça retry automático em erros
400,401,402ou422sem corrigir a entrada.