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.
409	`level_price_not_set`	Manca il prezzo configurato per questo account.
429	`rate_limit_exceeded`	Superato il limite di richieste al minuto.
500	(vari)	Errore interno. Riprova; se persiste, contatta il supporto.

Questo errore riguarda gli account che fanno parte di una rete con più livelli. Chi gestisce la rete può risolverlo impostando il prezzo del prodotto per il livello dell'account interessato.

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.

Mostrare sempre un messaggio chiaro all'utente e gestire i casi di errore più comuni rende la tua integrazione molto più robusta. In caso di errori che non riesci a interpretare, contatta il supporto Sterna.