Errori e risoluzione dei problemi

Autenticazione e consenso#

401: access token assente, scaduto o revocato. L’SDK prova il rinnovo quando applicabile. invalid_grant dal token endpoint indica refresh/code non valido o famiglia revocata: riavvia Connect. 403 insufficient_scope richiede un consenso con gli scope appropriati.

Limiti e modello#

402 weekly_limit_exceeded: attendi weekly_reset_at. 402 monthly_limit_exceeded: attendi period_end e il rinnovo pagato. 402 subscription_inactive: invita l’utente a verificare piano e pagamento nella console. 403 subscription_model_not_allowed: il servizio richiesto non è disponibile per il piano; contatta il supporto se capabilities() lo indica come disponibile.

429 subscription_requests_pending: l’account ha raggiunto il limite di richieste in corso. Attendi prima di inviarne altre. Il limite è condiviso fra le app dello stesso account. Se una richiesta precedente ha avuto un esito incerto, controlla il consumo prima di ripeterla.

Upload e audio#

413 invalid_transcription_file_size: invia un file non vuoto entro il limite documentato. 400/422: verifica formato, campi e body della richiesta; model non è accettato. 503 integration_chat_not_configured o subscription_transcription_not_configured: il servizio non è disponibile; aggiorna la UI usando capabilities() e consenti di riprovare in seguito.

Indisponibilità#

503 indica un’indisponibilità temporanea del servizio. Può includere subscription_exchange_rate_unavailable o subscription_key_provisioning_unavailable: conserva il codice per il supporto e invita a riprovare più tardi. Non modificare credenziali o payload per questi errori. Se il problema persiste, invia al supporto endpoint, timestamp e codice della risposta.

502 indica che la richiesta non ha ricevuto una risposta utilizzabile. Prima di ripetere un’inferenza con esito incerto, controlla il consumo e avvisa l’utente che una nuova chiamata può consumare nuovamente il piano.

Informazioni per il supporto#

Per una segnalazione raccogli client_id, timestamp UTC, endpoint, stato HTTP e codice di errore. Per i webhook aggiungi event_id e sequence. Non includere access token, refresh token, client secret, signing secret, file audio o prompt nei ticket. Se il consumo non è ancora aggiornato, rileggi usage() prima di ripetere una richiesta.