> ## Documentation Index > Fetch the complete documentation index at: https://docs.samsa.ai/llms.txt > Use this file to discover all available pages before exploring further. # Errori > L'envelope di errore della Samsa API, ogni codice di errore e come gestire ciascuno. Ogni errore che la Samsa API restituisce — per qualsiasi endpoint, a qualsiasi stato — usa un unico **envelope** JSON coerente. Analizza il `code` leggibile dalla macchina, non il `message` umano (i messaggi possono cambiare; i codici sono stabili). ## L'envelope di errore ```json theme={null} { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "The provided API key is invalid, expired, or revoked.", "request_id": "req_8f14e45fceea167a" } } ``` | Campo | Descrizione | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `error.type` | Categoria ampia, es. `authentication_error`, `credit_error`, `rate_limit_error`. | | `error.code` | Codice stabile e specifico su cui ramificare (la tabella qui sotto). | | `error.message` | Spiegazione leggibile dall'uomo. Per la visualizzazione e i log — non analizzarla. | | `error.request_id` | Id di correlazione per questa richiesta, restituito anche come header di risposta `X-Request-ID`. **Citalo quando contatti il supporto.** | | `error.param` | Presente sugli errori di validazione e di scope — nomina il campo problematico o `"scope"`. | Le risposte andate a buon fine non contengono mai un oggetto `error`. Ramifica prima sullo stato HTTP, poi su `error.code`. ## Codici di errore | HTTP | `code` | `type` | Significato | | ---- | ---------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | 401 | `invalid_api_key` | `authentication_error` | Chiave mancante, malformata, sconosciuta, scaduta o revocata. | | 403 | `missing_scope` | `permission_error` | Chiave valida a cui manca lo scope dell'endpoint. | | 402 | `insufficient_credits` | `credit_error` | Il pool di credits dell'organizzazione è al di sotto del costo dell'azione. | | 402 | `subscription_inactive` | `credit_error` | Nessun abbonamento utilizzabile per l'organizzazione. | | 402 | `insufficient_team_credits` | `credit_error` | Il budget mensile rimanente del team della chiave API (più i top-up) è al di sotto del costo dell'azione. | | 402 | `insufficient_unallocated_credits` | `credit_error` | Il pool non allocato dell'organizzazione (più i top-up) è al di sotto del costo dell'azione — chiave non assegnata a un team con budget. | | 404 | `not_found` | `invalid_request_error` | Id sconosciuto, o risorsa posseduta da un'altra organizzazione. | | 422 | `validation_error` | `invalid_request_error` | Il corpo della richiesta o i parametri non hanno superato la validazione. | | 429 | `rate_limited` | `rate_limit_error` | Finestra di rate di richieste per chiave superata. | | 429 | `too_many_active_jobs` | `rate_limit_error` | Raggiunto il tetto di job concorrenti dell'organizzazione. | | 500 | `internal_error` | `api_error` | Errore del server inaspettato. | *** ### `invalid_api_key` **HTTP 401.** L'header `Authorization` è mancante o malformato, oppure la chiave è sconosciuta, scaduta o revocata — oppure il creatore della chiave non è più membro dell'organizzazione. Le chiavi scadute e quelle sconosciute sono intenzionalmente indistinguibili. ```json theme={null} { "error": { "type": "authentication_error", "code": "invalid_api_key", "message": "The provided API key is invalid, expired, or revoked.", "request_id": "req_8f14e45fceea167a" } } ``` **Come gestirlo.** Controlla l'header `Authorization: Bearer samsa_sk_…`. Se la chiave è stata revocata o è scaduta, [creane una nuova](/it/guides/authentication#ruotare-una-chiave). Non riprovare — il risultato non cambierà. ### `missing_scope` **HTTP 403.** La chiave è valida ma le manca lo [scope](/it/guides/authentication#scope) richiesto dall'endpoint. `param` è `"scope"` e il messaggio nomina lo scope mancante. ```json theme={null} { "error": { "type": "permission_error", "code": "missing_scope", "message": "The API key is missing the required scope: images.generate.", "request_id": "req_1c9a3b7d2e5f4a80", "param": "scope" } } ``` **Come gestirlo.** Un admin modifica gli scope della chiave (o emette una nuova chiave) per concedere lo scope nominato. Non riprovare senza cambiare la chiave. ### `insufficient_credits` **HTTP 402.** Il pool di credits spendibili dell'organizzazione (abbonamento più top-up validi) è al di sotto del costo dell'azione. Consulta [Prezzi](/it/guides/pricing). Se l'organizzazione ha almeno un team attivo, l'API restituisce invece i codici legati ai team [`insufficient_team_credits`](#insufficient_team_credits) o [`insufficient_unallocated_credits`](#insufficient_unallocated_credits). ```json theme={null} { "error": { "type": "credit_error", "code": "insufficient_credits", "message": "Insufficient credits available.", "request_id": "req_2d5f4a801c9a3b7d" } } ``` **Come gestirlo.** Ricarica o esegui l'upgrade del piano dell'organizzazione nell'app, poi riprova. Nulla è stato addebitato e nessun job è stato creato. ### `subscription_inactive` **HTTP 402.** L'organizzazione non ha alcun abbonamento utilizzabile (nessuno attivo, in periodo di grazia o con top-up spendibili). Distinto da `insufficient_credits`, dove un abbonamento esiste ma il pool è troppo basso. ```json theme={null} { "error": { "type": "credit_error", "code": "subscription_inactive", "message": "No active subscription for this organization.", "request_id": "req_4a801c9a3b7d2d5f" } } ``` **Come gestirlo.** Riattiva la fatturazione per l'organizzazione nell'app, poi riprova. ### `insufficient_team_credits` **HTTP 402.** Le organizzazioni possono suddividere i loro credits mensili dell'abbonamento in **budget** per team, e ogni chiave API può essere assegnata a un team. Una chiave assegnata a un team con budget spende dal bucket mensile di quel team; tutto ciò che non è allocato ad alcun budget di team forma il **pool non allocato** dell'organizzazione. I top-up acquistati sono esenti dai budget e restano disponibili per coprire il resto. Questo codice si verifica quando il budget rimanente del team per il periodo di fatturazione corrente, più i top-up, è al di sotto del costo dell'azione. ```json theme={null} { "error": { "type": "credit_error", "code": "insufficient_team_credits", "message": "Insufficient team credits for team Marketing", "request_id": "req_6b7d2d5f4a801c9a" } } ``` **Come gestirlo.** Un admin dell'organizzazione può aumentare il budget mensile del team, assegnare la chiave a un altro team, oppure acquistare top-up (i top-up non sono limitati dai budget di team). L'utilizzo del budget si azzera inoltre con il prossimo periodo di fatturazione. Nulla è stato addebitato e nessun job è stato creato. ### `insufficient_unallocated_credits` **HTTP 402.** La chiave non è assegnata a un team con budget (non assegnata, o il suo team non ha budget), quindi spende dal pool non allocato dell'organizzazione — i credits mensili dell'abbonamento rimanenti dopo aver sottratto i budget di tutti i team attivi. Questo codice si verifica quando quel pool, più i top-up esenti dai budget, è al di sotto del costo dell'azione. Le organizzazioni senza alcun team attivo non vedono mai i due codici legati ai team — ricevono invece il semplice [`insufficient_credits`](#insufficient_credits). ```json theme={null} { "error": { "type": "credit_error", "code": "insufficient_unallocated_credits", "message": "Insufficient unallocated organization credits", "request_id": "req_0a3b7d2d5f4a801c" } } ``` **Come gestirlo.** Un admin dell'organizzazione può liberare credits non allocati abbassando i budget dei team, assegnare la chiave a un team con budget disponibile, eseguire l'upgrade del piano o acquistare top-up. Nulla è stato addebitato e nessun job è stato creato. ### `not_found` **HTTP 404.** L'id è sconosciuto, oppure appartiene a un'altra organizzazione. I due casi sono indistinguibili per progettazione, così l'esistenza non viene mai rivelata tra organizzazioni. ```json theme={null} { "error": { "type": "invalid_request_error", "code": "not_found", "message": "The requested resource was not found.", "request_id": "req_7d2d5f4a801c9a3b" } } ``` **Come gestirlo.** Verifica l'id e che l'organizzazione della chiave possieda la risorsa. Non riprovare. ### `validation_error` **HTTP 422.** Il corpo della richiesta o un parametro non ha superato la validazione. `param` nomina il campo problematico; `message` spiega il vincolo. ```json theme={null} { "error": { "type": "invalid_request_error", "code": "validation_error", "message": "aspect_ratio must be one of: 1:1, 1:4, 1:8, 16:9, 2:3, 21:9, 3:2, 3:4, 4:1, 4:3, 4:5, 5:4, 8:1, 9:16.", "request_id": "req_3b7d2d5f4a801c9a", "param": "aspect_ratio" } } ``` **Come gestirlo.** Correggi la richiesta seguendo `message` e `param`, poi reinviala. Questo è un errore del client — riprovare la stessa richiesta fallirà in modo identico. ### `rate_limited` **HTTP 429.** La chiave ha superato la sua finestra di rate di richieste per chiave. La risposta contiene gli header `Retry-After` e `X-RateLimit-*`. Consulta [Rate limits](/it/guides/rate-limits). ```json theme={null} { "error": { "type": "rate_limit_error", "code": "rate_limited", "message": "API rate limit exceeded. Slow down and retry after the rate-limit window resets.", "request_id": "req_5f4a801c9a3b7d2d" } } ``` **Come gestirlo.** Fai back-off e riprova dopo l'intervallo `Retry-After`. Usa un backoff esponenziale per 429 ripetuti. ### `too_many_active_jobs` **HTTP 429.** L'organizzazione ha raggiunto il suo tetto di job concorrenti in corso. Il messaggio include il conteggio attuale e il limite, ed è impostato un header `Retry-After`. ```json theme={null} { "error": { "type": "rate_limit_error", "code": "too_many_active_jobs", "message": "Too many active jobs for this organization (5/5). Wait for in-flight jobs to finish before submitting more.", "request_id": "req_801c9a3b7d2d5f4a" } } ``` **Come gestirlo.** Aspetta che i job in corso raggiungano uno stato terminale (interroga il loro endpoint `GET` o usa un [webhook](/it/guides/webhooks)) prima di inviarne altri, poi riprova dopo `Retry-After`. ### `internal_error` **HTTP 500.** Un errore inaspettato dalla parte di Samsa. La risposta non rivela mai dettagli interni — il `request_id` è il tuo riferimento per il supporto. ```json theme={null} { "error": { "type": "api_error", "code": "internal_error", "message": "An internal error occurred. Contact support with the request_id.", "request_id": "req_9a3b7d2d5f4a801c" } } ``` **Come gestirlo.** Riprova con backoff — i 500 sono spesso transitori. Se persiste, contatta [support@samsa.ai](mailto:support@samsa.ai) con il `request_id`. ## Usare `request_id` per il supporto Ogni errore (e ogni successo) porta un `request_id`, restituito anche come header di risposta `X-Request-ID`. Collega il tuo errore lato client, l'header di risposta e i log del server di Samsa a una singola richiesta. Registralo e citalo quando contatti [support@samsa.ai](mailto:support@samsa.ai) — è il modo più rapido per noi di trovare esattamente cosa è successo. Nuovi codici di errore possono essere aggiunti nel tempo (per esempio, codici additivi per endpoint). Tratta un `code` non riconosciuto come la sua classe di stato HTTP e ramifica sempre su `code` invece di confrontare il testo di `message`.