Códigos de error
La API de PolyTest usa los códigos de estado HTTP estándar. Todas las respuestas de error devuelven un cuerpo JSON con un campo error que describe el problema.
"error" que contiene un mensaje legible. El código de estado HTTP indica la categoría del error.400Bad Request
La solicitud está mal formada o le faltan parámetros obligatorios.
{ "error": "timestamp query parameter is required" }Causas comunes
- Falta un parámetro de consulta obligatorio
- Formato de parámetro no válido (p. ej., una marca de tiempo que no es ISO 8601)
- Valor de parámetro no válido, fuera del rango permitido
401Unauthorized
Error de autenticación: la solicitud no tiene credenciales válidas.
{ "error": "Invalid API key" }Causas comunes
- Falta la cabecera X-API-Key o la cabecera Authorization
- La clave de API no existe o no es válida
- La clave de API se ha revocado
- La clave de API ha caducado
- El token JWT no es válido o ha caducado
403Forbidden
Las credenciales son válidas, pero no tienen permiso para esta acción.
{ "error": "Admin access required" }Causas comunes
- Intento de acceder a endpoints solo para administradores (sync, seed) sin privilegios de administrador
- El alcance de la clave de API no incluye el permiso necesario
404Not Found
El recurso solicitado no existe.
{ "error": "Market not found" }Causas comunes
- El ID de mercado no existe
- El slug del mercado no coincide con ningún registro
- No se encontró ningún snapshot dentro de ±2 segundos de la marca de tiempo indicada
429Too Many Requests
Límite de tasa superado. Espera y vuelve a intentarlo pasado el tiempo indicado.
{ "error": "Rate limit exceeded" }Causas comunes
- Se superó el límite de solicitudes por minuto de tu plan
- Límite de ráfaga superado (demasiadas solicitudes en un intervalo corto)
500Internal Server Error
Se produjo un error inesperado en el servidor. Son poco frecuentes; si persiste, contacta con soporte.
{ "error": "Internal server error" }Causas comunes
- Problema de conexión con la base de datos
- Fallo de un servicio upstream
- Excepción inesperada en el servidor
Gestión de errores
Errores del cliente (4xx)
No reintentes automáticamente. Corrige los parámetros de la solicitud o la autenticación, o comprueba que el recurso existe antes de reintentar.
Errores del servidor (5xx)
Se pueden reintentar con seguridad usando backoff exponencial. Empieza con un retraso de 1 segundo y duplícalo en cada intento, hasta 3 reintentos.
import time
import requests
def api_request(url, headers, max_retries=3):
for attempt in range(max_retries):
response = requests.get(url, headers=headers)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 2 ** attempt))
time.sleep(wait)
continue
if response.status_code >= 500:
time.sleep(2 ** attempt)
continue
return response
raise Exception("Max retries exceeded")