Errori

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

{
  "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.

{
  "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. Non riprovare — il risultato non cambierà.

`missing_scope`

HTTP 403. La chiave è valida ma le manca lo scope richiesto dall’endpoint. param è "scope" e il messaggio nomina lo scope mancante.

{
  "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. Se l’organizzazione ha almeno un team attivo, l’API restituisce invece i codici legati ai team insufficient_team_credits o insufficient_unallocated_credits.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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) 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.

{
  "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 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 — è 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.

Per iniziare

API

Verifica dei contenuti

L’envelope di errore

Codici di errore

`invalid_api_key`

`missing_scope`

`insufficient_credits`

`subscription_inactive`

`insufficient_team_credits`

`insufficient_unallocated_credits`

`not_found`

`validation_error`

`rate_limited`

`too_many_active_jobs`

`internal_error`

Usare `request_id` per il supporto

​L’envelope di errore

​Codici di errore

​invalid_api_key

​missing_scope

​insufficient_credits

​subscription_inactive

​insufficient_team_credits

​insufficient_unallocated_credits

​not_found

​validation_error

​rate_limited

​too_many_active_jobs

​internal_error

​Usare request_id per il supporto

L’envelope di errore

Codici di errore

`invalid_api_key`

`missing_scope`

`insufficient_credits`

`subscription_inactive`

`insufficient_team_credits`

`insufficient_unallocated_credits`

`not_found`

`validation_error`

`rate_limited`

`too_many_active_jobs`

`internal_error`

Usare `request_id` per il supporto