Codici di errore
L’API di PolyTest usa i codici di stato HTTP standard. Tutte le risposte di errore restituiscono un body JSON con un campo error che descrive il problema.
"error" che contiene un messaggio leggibile. Il codice di stato HTTP indica la categoria dell’errore.400Bad Request
La richiesta non è valida o mancano parametri obbligatori.
{ "error": "timestamp query parameter is required" }Cause comuni
- Manca un parametro di query obbligatorio
- Formato del parametro non valido (ad es. timestamp non ISO 8601)
- Valore del parametro fuori dall’intervallo consentito
401Unauthorized
Autenticazione non riuscita: la richiesta non ha credenziali valide.
{ "error": "Invalid API key" }Cause comuni
- Manca l’header X-API-Key o l’header Authorization
- La chiave API non esiste o non è valida
- La chiave API è stata revocata
- La chiave API è scaduta
- Il token JWT non è valido o è scaduto
403Forbidden
Le credenziali sono valide ma non hanno i permessi per questa azione.
{ "error": "Admin access required" }Cause comuni
- Tentativo di accedere a endpoint riservati agli admin (sync, seed) senza privilegi di amministratore
- Lo scope della chiave API non include il permesso richiesto
404Not Found
La risorsa richiesta non esiste.
{ "error": "Market not found" }Cause comuni
- L’ID del mercato non esiste
- Lo slug del mercato non corrisponde ad alcun record
- Nessuno snapshot trovato entro ±2 secondi dal timestamp indicato
429Too Many Requests
Rate limit superato. Rallenta e riprova dopo il tempo indicato.
{ "error": "Rate limit exceeded" }Cause comuni
- Superato il limite di richieste al minuto del tuo piano
- Limite di burst superato (troppe richieste in un breve intervallo)
500Internal Server Error
Si è verificato un errore imprevisto sul server. Sono rari: se persiste, contatta il supporto.
{ "error": "Internal server error" }Cause comuni
- Problema di connessione al database
- Guasto di un servizio upstream
- Eccezione imprevista lato server
Gestione degli errori
Errori del client (4xx)
Non riprovare automaticamente. Correggi i parametri della richiesta o l’autenticazione, oppure verifica che la risorsa esista prima di riprovare.
Errori del server (5xx)
Puoi riprovare in sicurezza con un backoff esponenziale. Inizia con un ritardo di 1 secondo e raddoppialo a ogni tentativo, fino a 3 tentativi.
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")