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

# Sicurezza e risoluzione dei problemi

> Sicurezza, credits e accesso — e cosa fare quando un accesso va in loop, manca uno strumento o una chiamata viene rifiutata.

## Sicurezza, credits e accesso

<Warning>
  Le chiamate agli strumenti MCP sono **azioni reali sulla tua organizzazione** —
  spendono credits e creano asset esattamente come l'app e la REST API. Tratta una API
  key connessa a un client MCP come qualsiasi altro segreto di produzione.
</Warning>

* **Credits.** I nove strumenti multimediali — `generate_image`, `edit_image`,
  `img2img`, `create_variations`, `resize_image`, `upscale_image`, `remove_background`,
  `vectorize_image` e `generate_video` — prelevano dal
  [pool di credits](/it/guides/pricing) condiviso della tua organizzazione alle tariffe
  dell'app. Le letture e la gestione dei modelli sono gratuite. Controlla il saldo in
  qualsiasi momento con `get_credit_balance`.
* **Scope.** Ogni strumento richiede uno [scope](/it/guides/authentication#scope). Una
  API key o un token OAuth espone solo gli strumenti consentiti dai suoi scope —
  restringi una chiave esattamente a ciò di cui un'integrazione ha bisogno.
* **Revoca dell'accesso.** Un admin revoca una API key in **Settings → API Keys**; la
  revoca è definitiva e ha effetto alla chiamata immediatamente successiva. Per una
  connessione OAuth, disconnetti il connector nel tuo client (impostazioni dei
  connector di Claude o ChatGPT); gli access token possono anche essere revocati
  all'endpoint di revoca OAuth di Samsa. Una credenziale revocata smette di funzionare
  immediatamente.

## Risoluzione dei problemi

<AccordionGroup>
  <Accordion title="Richieste di accesso ripetute o 401" icon="triangle-exclamation">
    Un `401` è il server che chiede al client di (ri)autenticarsi.

    * **Client OAuth:** disconnetti il connector Samsa e riconnettiti per riavviare
      l'accesso. Se il consenso non si completa mai, faccelo sapere a
      [support@samsa.ai](mailto:support@samsa.ai).
    * **Client con API key:** verifica che l'header sia esattamente
      `Authorization: Bearer samsa_sk_...` e che la chiave sia valida — una chiave
      mancante, scaduta o revocata restituisce
      [`401 invalid_api_key`](/it/guides/errors#invalid_api_key). In caso di dubbio,
      crea una nuova chiave in **Settings → API Keys**.
  </Accordion>

  <Accordion title="Per quale organizzazione sto agendo?" icon="building">
    Una credenziale agisce sempre per **una sola organizzazione**. Una **API key**
    agisce per l'organizzazione che la possiede — per agire per un'altra org, usa una
    chiave creata in quell'org. Una connessione **OAuth** agisce per l'account e
    l'organizzazione con cui hai effettuato l'accesso — riconnettiti per cambiare. I
    credits vengono prelevati da, e gli asset appaiono in, quell'organizzazione.
  </Accordion>

  <Accordion title="Chiamata a uno strumento rifiutata — credits insufficienti" icon="coins">
    Se il saldo che questa connessione può spendere non copre una generazione, lo strumento
    di invio restituisce un errore strutturato **prima** che qualsiasi job venga eseguito —
    nulla viene addebitato. Il codice che ricevi dipende dallo scope di budget della
    connessione: [`insufficient_credits`](/it/guides/errors#insufficient_credits) quando
    l'organizzazione non ha team attivi,
    [`insufficient_team_credits`](/it/guides/errors#insufficient_team_credits) quando è
    assegnata a un team con budget, altrimenti
    [`insufficient_unallocated_credits`](/it/guides/errors#insufficient_unallocated_credits).
    Un guasto operativo nella detrazione stessa ricade sul generico
    `insufficient_credits` qualunque sia il regime — riprova prima di acquistare
    credits — e un'organizzazione di sistema esente dal budgeting per team resta nel
    regime `org` anche con team attivi. Controlla `get_credit_balance` — il suo `available` è il numero in cui deve rientrare il
    costo di un job, e il suo `scope` indica il regime di budget; sotto `team` o
    `unallocated`, confronta `plan_credits` con `scope.remaining` per vedere quale dei due
    vincola (sotto `org`, `scope.remaining` è `null` e solo `plan_credits` può vincolare) —,
    poi ricarica, aumenta il budget
    del team o esegui l'upgrade nell'[app Samsa](https://app.samsa.ai). Le letture sono
    sempre gratuite.
  </Accordion>

  <Accordion title="Rate limit o troppi job" icon="gauge-high">
    Tre limiti indipendenti possono rallentare una raffica di chiamate:

    * **Rate di richieste per chiave** — 60 richieste/minuto; l'eccesso restituisce
      [`rate_limited`](/it/guides/errors#rate_limited).
    * **Concorrenza per organizzazione** — al massimo 5 job in corso alla volta; un
      sesto restituisce
      [`too_many_active_jobs`](/it/guides/errors#too_many_active_jobs). Lascia finire i
      job (interroga `get_job_status`) prima di inviarne altri.
    * **Concorrenza del transport MCP** — una raffica di richieste `/mcp` simultanee su
      un singolo worker può restituire un transitorio `429 concurrency_limit_exceeded`
      con `Retry-After: 1`. Aspetta un secondo e riprova.

    Consulta [Rate limits](/it/guides/rate-limits) per il quadro completo e le
    indicazioni sul back-off.
  </Accordion>

  <Accordion title="Uno strumento manca o dice che gli manca uno scope" icon="lock">
    Gli strumenti che non puoi chiamare sono nascosti o rifiutati perché la credenziale
    connessa non ha il loro [scope](/it/guides/authentication#scope). Per esempio,
    `generate_image` necessita di `images.generate`. Modifica gli scope della chiave (o
    emetti una nuova chiave) in **Settings → API Keys**, poi riconnettiti.
  </Accordion>
</AccordionGroup>