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.
403	`svg_phase1_scope_out_required`	`permission_error`	Solo vettorizzazione: l’accettazione di esclusione di ambito ToS/AUP verificata lato server è mancante o scaduta.
402	`insufficient_credits`	`credit_error`	Il pool di credits dell’organizzazione è al di sotto del costo dell’azione — anche il fallback quando la detrazione stessa fallisce operativamente.
402	`subscription_inactive`	`credit_error`	Nessun abbonamento utilizzabile per l’organizzazione.
402	`insufficient_team_credits`	`credit_error`	Il saldo che la chiave API può spendere è al di sotto del costo dell’azione, e la chiave è assegnata a un team con budget.
402	`insufficient_unallocated_credits`	`credit_error`	Il saldo che la chiave API può spendere è al di sotto del costo dell’azione, e la chiave non è assegnata a un team con budget.
404	`not_found`	`invalid_request_error`	Id sconosciuto, o risorsa posseduta da un’altra organizzazione.
409	`upload_in_progress`	`invalid_request_error`	Solo upload di immagini: un’altra richiesta sta completando lo stesso upload proprio ora.
409	`idempotency_key_reused`	`invalid_request_error`	Con il miglioramento dei prompt (in arrivo): l’`Idempotency-Key` è già stato usato con un altro body di richiesta.
409	`idempotency_in_progress`	`invalid_request_error`	Con il miglioramento dei prompt (in arrivo): una richiesta con lo stesso `Idempotency-Key` è ancora in corso.
422	`validation_error`	`invalid_request_error`	Il corpo della richiesta o i parametri non hanno superato la validazione.
422	`svg_acceptance_required`	`invalid_request_error`	Solo vettorizzazione: `svg_acceptance` non è il booleano letterale `true`.
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.
429	`too_many_pending_uploads`	`rate_limit_error`	Solo upload di immagini: l’utente ha 20 upload in attesa di completamento.
500	`internal_error`	`api_error`	Errore del server inaspettato.
500	`refund_pending`	`api_error`	Con il miglioramento dei prompt (in arrivo): il provider è fallito e il rimborso del credit non è ancora confermato — Samsa lo ripete automaticamente.
502	`provider_error`	`api_error`	Con il miglioramento dei prompt (in arrivo): il provider di IA è fallito; il credit è stato rimborsato.
503	`service_unavailable`	`api_error`	Una funzione è disattivata o temporaneamente non disponibile — per esempio il miglioramento dei prompt, che non è ancora attivato. Con il miglioramento dei prompt (in arrivo), anche: Samsa non ha potuto confermare lo stato della richiesta.

`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 — con due eccezioni. Un’organizzazione di sistema esente dal budgeting per team resta nel regime org e mantiene questo codice generico anche con team attivi. E un guasto operativo nella detrazione stessa (per esempio una lettura del saldo degradata) ricade su questo codice generico qualunque sia il regime di budget. Un semplice insufficient_credits in una configurazione con team può quindi essere transitorio; riprova prima di trattarlo come un saldo esaurito.

{
  "error": {
    "type": "credit_error",
    "code": "insufficient_credits",
    "message": "Insufficient credits available.",
    "request_id": "req_2d5f4a801c9a3b7d"
  }
}

Come gestirlo. Se un successivo GET /credits mostra un available che copre il costo, potresti aver incontrato il fallback operativo — riprova una volta. Quella lettura è però un’istantanea: anche un cambiamento di stato dopo il rifiuto (un top-up, un rimborso, un budget modificato o un reset del periodo) può spiegarlo, quindi una reale carenza non è esclusa. Altrimenti 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 saldo che la chiave può spendere — il minore tra il pool del piano residuo dell’organizzazione e il budget residuo del team, più i top-up — è al di sotto del costo dell’azione. È esattamente l’available riportato da GET /credits.

Il codice indica il regime di budget, non il saldo che si è esaurito. Una chiave assegnata a un team con budget riceve questo codice anche quando a esaurirsi è stato il pool del piano dell’organizzazione e non il budget del team — il team può quindi mostrare ancora margine. Confronta plan_credits con scope.remaining su GET /credits per vedere quale dei due vincola.

{
  "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 il saldo che la chiave può spendere — il minore tra il pool del piano residuo dell’organizzazione e il margine di quel pool non allocato, più i top-up esenti dai budget — è al di sotto del costo dell’azione, con la stessa avvertenza vista sopra su quale saldo si sia davvero esaurito. Le organizzazioni senza alcun team attivo non vedono mai i due codici legati ai team — ricevono invece il semplice insufficient_credits.

Come anticiparlo. GET /credits riporta available — ciò che la chiave chiamante può spendere adesso — e un blocco scope che indica il suo regime di budget. Un job i cui estimated_credits rientrano in available non viene rifiutato con nessuno di questi tre codici, finché nel frattempo lo stato dei credits e dei budget/team non cambia — salvo il fallback operativo: una detrazione degradata può restituire il generico insufficient_credits anche in quel caso, quindi riprova prima.

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

`svg_acceptance_required`

HTTP 422. Solo POST /images/vectorizations restituisce questo codice. L’SVG è un’esclusione di ambito documentata ai sensi dell’art. 50(2) del regolamento europeo sull’IA: un SVG non può portare un manifesto C2PA né una filigrana incorporata, quindi gli output vettoriali sono consegnati non firmati. svg_acceptance deve perciò essere il booleano letterale true — un valore mancante, false o altro viene rifiutato con questo codice dedicato, mai con il validation_error generico. L’accettazione è divulgazione / prova di audit, non una rinuncia alla conformità. Non viene addebitato nulla e non viene creato alcun job.

{
  "error": {
    "type": "invalid_request_error",
    "code": "svg_acceptance_required",
    "message": "SVG (vector) output is an EU AI Act Art. 50(2) scope-out delivered unsigned and unwatermarked. Set `svg_acceptance` to true to acknowledge this before requesting a vectorization. The acknowledgment is disclosure — it records that you were informed the output is unsigned; it is not a compliance waiver.",
    "request_id": "req_3b7d2d5f4a801c9a"
  }
}

Come gestirlo. Reinvia la richiesta con "svg_acceptance": true non appena la tua integrazione mostra l’avviso di output non firmato a chi opera sul risultato.

`svg_phase1_scope_out_required`

HTTP 403. Anche questo riguarda solo la vettorizzazione ed è diverso da missing_scope — lo scope della chiave va bene. La consegna richiede inoltre un’accettazione dei ToS/AUP attuale e verificata lato server; il flag svg_acceptance della richiesta non è mai considerato quella prova. All’invio, un’accettazione mancante o scaduta viene rifiutata prima di qualsiasi addebito. Il controllo viene rieseguito alla consegna: un job già accettato può quindi essere ancora rifiutato da GET /images/vectorizations/{id} o all’invio del webhook se nel frattempo l’accettazione scade — un rifiuto in consegna non aggiunge addebiti, ma non rimborsa i crediti già consumati dal job completato.

{
  "error": {
    "type": "permission_error",
    "code": "svg_phase1_scope_out_required",
    "message": "SVG (vector) delivery requires a current, accepted Terms of Service / Acceptable Use Policy version that covers the Art. 50(2) scope-out. Your organization has not accepted the current version. Accept the latest ToS/AUP, then retry. Accepting it is disclosure that you were informed the output is unsigned; it is not a compliance waiver.",
    "request_id": "req_3b7d2d5f4a801c9a"
  }
}

Come gestirlo. Accetta i ToS/AUP correnti nell’app Samsa e riprova. Per un job rifiutato in consegna, richiedi di nuovo il suo stato GET — il webhook non viene reinviato automaticamente. Accettare è divulgazione, non una rinuncia.

`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.

`upload_in_progress`

HTTP 409. Solo upload di immagini: un’altra chiamata POST /images/uploads/{id}/complete per lo stesso upload è in corso.

{
  "error": {
    "type": "invalid_request_error",
    "code": "upload_in_progress",
    "message": "This upload is being completed by another request; call complete again in a few seconds. If this persists for more than a few minutes, prepare a new upload.",
    "request_id": "req_3b7d2d5f4a801c9a"
  }
}

Come gestirlo. Richiama complete tra qualche secondo — è idempotente. Se l’errore continua per più di qualche minuto, prepara un nuovo upload.

`idempotency_key_reused`

HTTP 409. Solo con il miglioramento dei prompt (in arrivo): l’header Idempotency-Key è già stato usato nelle ultime 24 ore con un body di richiesta diverso. Una chiave appartiene sempre a una sola richiesta. Non è stato addebitato nulla.

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key was already used with a different request body. Use a new key for a new request.",
    "request_id": "req_2d5f4a801c9a3b7d"
  }
}

Come gestirlo. Usa un nuovo Idempotency-Key per una nuova richiesta. Non riprovare con la stessa chiave — il risultato non cambierà.

`idempotency_in_progress`

HTTP 409. Solo con il miglioramento dei prompt (in arrivo): una richiesta con lo stesso Idempotency-Key e lo stesso body è ancora in corso. Questa richiesta non è stata addebitata.

{
  "error": {
    "type": "invalid_request_error",
    "code": "idempotency_in_progress",
    "message": "A request with this Idempotency-Key is still in progress. Retry in a few seconds.",
    "request_id": "req_7d2d5f4a801c9a3b"
  }
}

Come gestirlo. Riprova tra qualche secondo con la stessa chiave. Quando la prima richiesta è terminata, la ripetizione restituisce il suo risultato con Idempotency-Replayed: true.

`too_many_pending_uploads`

HTTP 429. Solo upload di immagini: hai 20 upload preparati ma non completati. Il messaggio include il conteggio attuale e il limite, ed è impostato un header Retry-After.

{
  "error": {
    "type": "rate_limit_error",
    "code": "too_many_pending_uploads",
    "message": "You have 20 uploads awaiting completion (limit 20). Complete them, or wait until unfinished ones expire, before preparing more.",
    "request_id": "req_9a3b7d2d5f4a801c"
  }
}

Come gestirlo. Completa gli upload che hai preparato, oppure aspetta che quelli non completati scadano (dopo Retry-After), poi prepara di nuovo.

`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.

`refund_pending`

HTTP 500. Solo con il miglioramento dei prompt (in arrivo): il provider di IA è fallito dopo l’addebito del credit e il rimborso non ha potuto essere confermato subito. Il rimborso è registrato e Samsa lo ripete automaticamente finché non va a buon fine.

{
  "error": {
    "type": "api_error",
    "code": "refund_pending",
    "message": "The prompt could not be improved. The refund of the charged credit is pending and will be completed automatically.",
    "request_id": "req_4a801c9a3b7d2d5f"
  }
}

Come gestirlo. Per il rimborso non devi fare nulla. Ripeti la richiesta più tardi con un nuovo Idempotency-Key (la vecchia chiave restituisce questo errore). Se il credit non è tornato dopo un’ora, contatta support@samsa.ai con il request_id.

`provider_error`

HTTP 502. Solo con il miglioramento dei prompt (in arrivo): il provider di IA è fallito o non ha restituito un risultato utilizzabile. Il credit addebitato per la chiamata è stato rimborsato prima di questa risposta.

{
  "error": {
    "type": "api_error",
    "code": "provider_error",
    "message": "The AI provider failed to improve the prompt. The charged credit was refunded.",
    "request_id": "req_9a3b7d2d5f4a801c"
  }
}

Come gestirlo. Riprova con backoff e un nuovo Idempotency-Key — la vecchia chiave restituisce questo errore. Alla fine non è stato addebitato nulla.

`service_unavailable`

HTTP 503. Una funzione è disattivata o temporaneamente non disponibile. Oggi è il caso del miglioramento dei prompt, che non è ancora attivato (Prompt improvement is not available yet.), e può riguardare anche altre funzioni, come la creazione di modelli. Con il miglioramento dei prompt (in arrivo), un 503 significa anche che Samsa non ha potuto confermare lo stato di idempotenza o l’esito dell’addebito della richiesta: nessun prompt è stato consegnato, e un credit addebitato viene rimborsato automaticamente.

{
  "error": {
    "type": "api_error",
    "code": "service_unavailable",
    "message": "Prompt improvement is not available yet.",
    "request_id": "req_801c9a3b7d2d5f4a"
  }
}

Come gestirlo. Riprova più tardi con backoff. Una funzione disattivata resta tale finché Samsa non la attiva — segui il changelog. Per il miglioramento dei prompt, un nuovo tentativo con lo stesso Idempotency-Key non viene mai addebitato due volte.

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

Guide

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`

`svg_acceptance_required`

`svg_phase1_scope_out_required`

`rate_limited`

`too_many_active_jobs`

`upload_in_progress`

`idempotency_key_reused`

`idempotency_in_progress`

`too_many_pending_uploads`

`internal_error`

`refund_pending`

`provider_error`

`service_unavailable`

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

​svg_acceptance_required

​svg_phase1_scope_out_required

​rate_limited

​too_many_active_jobs

​upload_in_progress

​idempotency_key_reused

​idempotency_in_progress

​too_many_pending_uploads

​internal_error

​refund_pending

​provider_error

​service_unavailable

​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`

`svg_acceptance_required`

`svg_phase1_scope_out_required`

`rate_limited`

`too_many_active_jobs`

`upload_in_progress`

`idempotency_key_reused`

`idempotency_in_progress`

`too_many_pending_uploads`

`internal_error`

`refund_pending`

`provider_error`

`service_unavailable`

Usare `request_id` per il supporto