Gestione degli errori
Quando una richiesta non va a buon fine, l'API Sterna non si limita a fallire: restituisce sempre un'indicazione chiara di cosa è andato storto. Gestire correttamente gli errori rende la tua integrazione affidabile e più facile da mantenere.
Come sono fatti gli errori
Quando una richiesta fallisce, l'API risponde con un codice di stato HTTP che indica il tipo di problema, e con un corpo in formato JSON che contiene un campo error con la descrizione dell'errore. Per esempio:
{
"error": "missing_product_id"
}Il codice di stato HTTP ti dice a grandi linee cosa è successo: i codici che iniziano per 4 indicano un problema nella richiesta (qualcosa da correggere da parte tua), mentre i codici che iniziano per 5 indicano un problema temporaneo lato Sterna.
Tabella degli errori
Questi sono gli errori che puoi incontrare usando l'API:
| Codice | Errore | Significato |
|---|---|---|
| 401 | unauthorized | API key mancante o non valida. |
| 403 | insufficient_scope | La chiave non ha il permesso write necessario. |
| 400 | invalid_json_body | Il corpo della richiesta non è un JSON valido. |
| 400 | missing_product_id | Manca il campo product_id. |
| 402 | (plafond) | Plafond insufficiente per completare l'ordine. |
| 404 | order_not_found | L'ordine richiesto non esiste o non è tuo. |
| 404 | product_not_found | Il prodotto richiesto non esiste. |
| 429 | rate_limit_exceeded | Superato il limite di richieste al minuto. |
| 500 | (vari) | Errore interno. Riprova; se persiste, contatta il supporto. |
Consigli pratici
Per un'integrazione solida, gestisci sempre questi casi nel tuo codice:
- Errori `401` e `403` — Riguardano l'autenticazione e i permessi. Verifica che la API key sia corretta, valida e con i permessi adeguati all'operazione.
- Errori `400` e `404` — Riguardano i dati della richiesta. Controlla che il corpo sia un JSON valido e che gli identificativi (prodotto, ordine) siano corretti.
- Errore `429` — Hai superato il limite di richieste. Attendi il tempo indicato prima di riprovare (vedi la sezione "Limiti di utilizzo").
- Errori `500` — Sono temporanei e lato Sterna. Riprova dopo qualche istante; se l'errore persiste, contatta il supporto.