Errores

Todas las API devuelven los errores con la misma estructura:

{
  "error": {
    "code": "invalid_request",
    "message": "The field 'email' is required.",
    "request_id": "req_123"
  }
}

Incluye request_id cuando contactes a soporte.

Códigos de estado

Estado	Código	Qué hacer
`400`	`invalid_request`	Corrige la solicitud. Reintentar no ayudará.
`401`	`unauthorized`	Revisa que tu clave de API sea correcta y no esté revocada.
`402`	`insufficient_credits`	Agrega créditos o activa la recarga automática y reintenta.
`403`	`pro_required`	Suscríbete a Pro. Las solicitudes en vivo a productos de pago lo requieren.
`403`	`account_suspended`	Contacta a soporte.
`403`	`forbidden`	Tu clave no tiene acceso a este recurso.
`404`	`not_found`	Revisa el ID y si estás en modo de prueba o en vivo.
`409`	`conflict`	El recurso no permite eso ahora, como cancelar una verificación ya enviada.
`409`	`idempotency_key_reused`	Usa un `Idempotency-Key` nuevo para una solicitud distinta.
`409`	`request_in_progress`	El primer intento sigue en curso. Reintenta en un momento.
`409`	`retry_later`	Espera los segundos de `Retry-After` y reintenta.
`413`	`payload_too_large`	Envía un cuerpo de menos de 1 MB.
`429`	`rate_limited`	Espera y reintenta. Consulta los límites.
`500`	`internal_error`	Reintenta con espera progresiva.
`503`	`service_unavailable`	Reintenta con espera progresiva.

Decide según code, no según message: los códigos son estables y los mensajes pueden cambiar de redacción.

Todas las respuestas, exitosas o no, también llevan el ID en el encabezado X-Request-Id.

Agrega el encabezado Idempotency-Key a las solicitudes POST. Sirve cualquier texto único de hasta 255 caracteres, como un UUID.

Si la primera solicitud tuvo éxito, un reintento con la misma clave devuelve esa misma respuesta, con el encabezado Idempotent-Replayed: true, y el trabajo no se repite.
Si la primera solicitud fue rechazada o falló, no se guarda nada, así que un reintento la ejecuta de nuevo.
Las claves se recuerdan durante 24 horas, por separado en modo de prueba y en vivo.