Patrones

Códigos de error

Tverificas usa códigos HTTP estándar. El cuerpo de la respuesta incluye un campo `detail` con un mensaje legible.

Forma de respuesta

json

{
  "detail": "Mensaje legible para el cliente",
  "code": "quota_exceeded"
}

Código	Significado	Causa típica
`400`	Bad Request	Body inválido. Falta cédula, endpoint inexistente, formato incorrecto.
`401`	Unauthorized	API key ausente, mal formada, o cabecera Authorization no presente.
`403`	Forbidden	API key revocada, organización suspendida, o sin permisos para el endpoint.
`404`	Not Found	ID de búsqueda no existe o no pertenece a tu organización.
`409`	Conflict	Idempotency-Key reutilizada con un body distinto al original.
`422`	Unprocessable	Cuota mensual agotada o límite de modo test alcanzado.
`429`	Too Many Requests	Excediste el rate-limit. Espera unos segundos y reintenta con backoff.
`500`	Server Error	Error interno. Reintenta con backoff exponencial. Si persiste, contacta soporte.
`502`	Bad Gateway	Una fuente upstream falló. La búsqueda puede quedar en degraded.
`503`	Service Unavailable	Mantenimiento temporal. Reintenta en unos segundos.

Para 5xx y 429: backoff exponencial con jitter (1s, 2s, 4s, …). Para 4xx (excepto 409 y 429): no reintentes — el error es permanente.