Gestión de errores

Todos los errores de la API siguen un formato coherente. Así puedes gestionarlos sin problemas.

Formato de la respuesta de error

Cuando se produce un error, la API devuelve un objeto JSON con esta estructura:

json

{
  "error": "Validation Error",
  "message": "The email field is required.",
  "status_code": 422
}

Código de estado	Error	Causa y solución
`400`	Solicitud incorrecta	JSON mal formado o faltan campos obligatorios. Revisa el cuerpo de tu solicitud.
`401`	No autorizado	Falta la API key o no es válida. Revisa tu cabecera `Authorization` .
`402`	Pago requerido	Créditos insuficientes. Compra más créditos o espera a que se restablezca el límite diario.
`422`	Error de validación	El formato de la dirección de email no es válido. Revisa el valor que estás enviando.
`429`	Demasiadas solicitudes	Se ha superado el límite de solicitudes. Revisa la cabecera `Retry-After` y espera.
`500`	Error interno del servidor	Algo ha fallado por nuestra parte. Vuelve a intentarlo en unos segundos. Contacta con soporte si sigue fallando.

json

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key",
  "status_code": 401
}

Solución: Comprueba que tu cabecera Authorization tenga el formato correcto: Bearer YOUR_API_KEY. Verifica tu key en el panel.

json

{
  "error": "Validation Error",
  "message": "The email field must be a valid email address.",
  "status_code": 422
}

Solución: Asegúrate de que el valor del email tenga un formato válido (p. ej., user@example.com). Limpia tus datos antes de enviarlos.

json

{
  "error": "Too Many Requests",
  "message": "Rate limit exceeded. Please slow down.",
  "status_code": 429,
  "retry_after": 15
}

Solución: Espera el número de segundos indicado en retry_after antes de reintentar. Consulta Límites de solicitudes →

✅ La API key empieza por ev_ y es correcta
✅ Authorization formato de la cabecera: Bearer YOUR_KEY (no Token o Basic)
✅ Content-Type: application/json la cabecera está configurada
✅ El cuerpo de la solicitud es JSON válido
✅ email el campo es un string, no null ni ausente
✅ Te quedan créditos (consulta Créditos →)