Skip to main content
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

Le risposte andate a buon fine non contengono mai un oggetto error. Ramifica prima sullo stato HTTP, poi su error.code.

​
Codici di errore

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