Risoluzione dei problemi

Questa pagina raccoglie i problemi che capita più spesso di incontrare quando si integra l'API Sterna, organizzati per sintomo: cosa osservi, qual è la causa probabile, cosa puoi fare per risolvere.

È una guida pratica e si appoggia alle altre sezioni della documentazione. Per il riferimento tecnico codice→significato di ogni errore vedi «Gestione degli errori». Se il tuo caso non rientra in quelli qui sotto, vedi «Supporto».

Problemi di autenticazione e chiavi

Ricevo 401 Unauthorized su qualsiasi chiamata.

Causa probabile. L'header Authorization manca, è scritto male, o la chiave non è valida (per esempio è stata copiata solo in parte o contiene spazi).

• Verifica che l'header abbia esattamente questa forma: Authorization: Bearer <chiave>.
• Controlla che la chiave inizi con stk_test_ (ambiente test) o stk_live_ (ambiente live) e sia copiata per intero.
• Controlla che non ci siano spazi a inizio o fine della chiave, e che non sia stato troncato nulla.
• Se hai più chiavi, assicurati di non averne usata una vecchia o revocata.

Ricevo 403 insufficient_scope quando provo a creare un ordine.

Causa probabile. La chiave che stai usando ha solo permessi di lettura: le chiamate GET funzionano, ma POST /v1/orders viene rifiutata perché manca lo scope write.

• Genera o usa una chiave con scope write per le chiamate che creano ordini. Le chiavi e i loro scope si gestiscono dal pannello, non via API.
• Se nella tua integrazione separi lettura e scrittura, controlla di non aver invertito le due chiavi.

Problemi di ambiente

Pensavo di essere in test ma l'ordine è andato in live (o viceversa).

Causa probabile. La chiave usata appartiene all'ambiente opposto a quello che credevi. Ambiente test e ambiente live sono completamente separati: la chiave determina in quale dei due la chiamata viene eseguita.

• Controlla il prefisso della chiave: stk_test_ = test, stk_live_ = live.
• In alternativa chiama GET /v1/me con la chiave in questione: il campo environment ti dice se sei in test o in live.
• Nei tuoi sistemi, tieni le chiavi dei due ambienti in variabili nettamente distinte (per esempio una variabile per il test, una diversa per il live) per evitare scambi.

Problemi sugli ordini

Ricevo 404 product_not_found o order_not_found.

Causa probabile. L'id che hai passato non esiste, oppure esiste ma appartiene a un altro account o a un altro ambiente. Gli identificativi non sono condivisi fra test e live.

• Per product_not_found: rileggi il catalogo con GET /v1/catalog nell'ambiente in cui stai operando e usa un id presente in quella risposta.
• Per order_not_found: usa l'id restituito dalla creazione dell'ordine (POST /v1/orders ti restituisce un oggetto order con il campo id e il campo order_number).
• Verifica di star chiamando con la chiave dell'ambiente giusto: un ordine creato in test non esiste in live, e viceversa.

Ricevo 402: plafond insufficiente.

Causa probabile. Il plafond residuo del tuo account non è sufficiente a coprire il costo dell'ordine. Quando succede, l'ordine non viene creato e dal plafond non viene scalato nulla.

• Ricarica il plafond. Le ricariche si fanno dal pannello, non via API.
• In attesa della ricarica, puoi continuare a operare in ambiente test, che non consuma plafond.

Ricevo 409 level_price_not_set: l'ordine non viene creato.

Causa probabile. Il tuo account fa parte di un gruppo (rete a più livelli) e per il prodotto richiesto non è stato impostato un prezzo per il tuo livello. Senza un prezzo applicabile, l'ordine non può essere creato.

• Chi gestisce il gruppo (l'account principale) deve impostare il prezzo del prodotto per il livello del tuo account. L'operazione si fa dal pannello.
• Nell'attesa, puoi provare lo stesso flusso con altri prodotti per i quali il prezzo del tuo livello è già impostato.

Il prezzo dell'ordine non coincide con quello del catalogo.

Causa probabile. Comportamento normale per un account che fa parte di un gruppo: il prezzo applicato all'ordine è quello stabilito per il tuo livello, non quello di riferimento del catalogo.

Confronta il campo unit_price_eur della risposta a POST /v1/orders (o GET /v1/orders/{id}) con price_eur del catalogo: è normale che siano diversi se sei in un gruppo. Il campo total_price_eur è semplicemente unit_price_eur × quantity. Non è richiesta nessuna azione: l'ordine è valido.

Ho creato l'ordine ma l'eSIM non è nella risposta.

Causa probabile. Comportamento normale: l'evasione di un ordine è asincrona. La risposta a POST /v1/orders restituisce subito un order con status processing; i dati dell'eSIM compaiono solo quando lo status diventa completed, dopo qualche secondo.

• Attendi qualche secondo e richiama GET /v1/orders/{id} usando l'id restituito dalla creazione.
• Ripeti la richiesta a intervalli (per esempio ogni 2–3 secondi) finché status non è completed: a quel punto i dati dell'eSIM sono presenti nella risposta.
• Se dopo un tempo ragionevole lo status è failed, l'evasione non è riuscita: il motivo è nel campo error dell'ordine.

Limiti

Ricevo 429 rate_limit_exceeded.

Causa probabile. Hai superato il numero di richieste al minuto consentito. Tipicamente succede quando si interroga GET /v1/orders/{id} in loop molto stretto per attendere il completamento di un ordine, o quando più processi chiamano l'API in parallelo senza coordinarsi.

• Aspetta il numero di secondi indicato nel campo retry_after_seconds della risposta di errore, poi riprova.
• Aumenta l'intervallo fra una chiamata di polling e la successiva (per esempio 2–3 secondi invece di chiamare in continuo).
• Quando applicabile, introduci un backoff progressivo: a ogni 429 raddoppia l'attesa prima del prossimo tentativo.