Manejo de Errores

La API utiliza códigos de estado HTTP estándar para indicar el éxito o fallo de una solicitud. Todas las respuestas de error siguen un formato JSON consistente.

Formato de Respuesta de Error

{
  "message": "Human-readable error description",
  "error": "error_code"
}

Campo	Tipo	Descripción
message	string	Una descripción legible del error
error	string	Un código de error legible por máquina

Códigos de Error

401 — No Autorizado

El client secret falta, es inválido o pertenece a un cliente inactivo.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "message": "Invalid or inactive client secret",
  "error": "unauthorized"
}

Causas comunes:

• El header X-Client-Secret falta en la solicitud.
• El UUID está malformado o no coincide con ningún cliente.
• La cuenta del cliente ha sido desactivada.

Resolución: Verifique que su client secret sea correcto y esté activo. Consulte Autenticación.

---

404 — No Encontrado

El recurso o endpoint solicitado no existe.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "message": "Resource not found",
  "error": "not_found"
}

Causas comunes:

• Ruta URL incorrecta (ej., error tipográfico en el endpoint).
• Acceso a un recurso que no existe.

Resolución: Verifique la URL del endpoint contra la Referencia API.

---

422 — Error de Validación

Uno o más parámetros de consulta son inválidos.

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The given data was invalid.",
  "error": "validation_error"
}

Causas comunes:

• Formato de fecha inválido (se espera YYYY-MM-DD).
• Valor de transaction_type inválido (debe ser DEBIT, CREDIT, ROLLBACK o FREE_SPIN).
• Valor no numérico para page o per_page.
• Código ISO de moneda inválido.

Resolución: Revise la sección de parámetros de consulta de la documentación del endpoint correspondiente.

---

429 — Demasiadas Solicitudes

Ha excedido el límite de 60 solicitudes por minuto.

HTTP/1.1 429 Too Many Requests
Content-Type: application/json

{
  "message": "Too many requests. Please try again later.",
  "error": "too_many_requests"
}

Resolución: Implemente limitación de solicitudes en su integración. Espere al menos 60 segundos antes de reintentar. Considere almacenar en caché las respuestas para datos que no cambian frecuentemente.

Estrategia de Límite de Solicitudes

• Almacene en caché las respuestas cuando los datos no necesiten ser en tiempo real.
• Use filtros de fecha para reducir el tamaño de las respuestas y minimizar el número de solicitudes.
• Implemente retroceso exponencial al reintentar después de una respuesta 429.

---

500 — Error del Servidor

Ocurrió un error inesperado en el servidor.

HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "message": "An unexpected error occurred. Please try again later.",
  "error": "server_error"
}

Resolución: Este es un problema del lado del servidor. Si el error persiste, contacte al soporte con los detalles de su solicitud (endpoint, parámetros, marca de tiempo).

Mejores Prácticas

1. Siempre verifique el código de estado HTTP antes de procesar el cuerpo de la respuesta.
2. Maneje los errores de forma elegante — muestre mensajes significativos a sus usuarios.
3. Implemente lógica de reintento con retroceso exponencial para errores 429 y 500.
4. Registre las respuestas de error (excluyendo el client secret) para depuración.
5. No reintente errores 401 — requieren acción correctiva (corregir el secret), no reintentar.
6. No reintente errores 422 — indican un problema con los parámetros de su solicitud.