> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errori

> Come il merchant MCP segnala i fallimenti: rifiuti HTTP, risultati isError con codici stabili e regole di retry per le scritture andate in timeout.

I fallimenti emergono a due livelli. I problemi di autenticazione, origin e rate-limit vengono rifiutati **prima** di MCP, come normali risposte HTTP. Tutto ciò che accade all'interno di una chiamata a uno strumento torna come risultato dello strumento MCP con `isError: true`.

## Livello HTTP

| Status | Causa | Body |
| - | - | - |
| `401` | Credenziale mancante o non valida | Header `WWW-Authenticate: Bearer realm="OAuth", resource_metadata="…"`; avvia la discovery OAuth |
| `403` | Header `Origin` non presente in allow-list | `{ "error": "Origin not allowed" }` |
| `429` | Più di 60 richieste al minuto per questo utente o key | `{ "error": "Rate limit exceeded" }` con `Retry-After` in secondi |

Questi sono al di fuori dell'envelope MCP; una libreria client MCP tipicamente li solleva come errori di trasporto.

## Errori dello strumento

Una chiamata fallita a uno strumento è un normale successo JSON-RPC il cui risultato ha `isError: true`, un singolo blocco di testo e **nessun** `structuredContent`:

```json theme={null}
{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "{\"error\":{\"code\":\"INVALID_INPUT\",\"message\":\"Date range exceeds 90 days\",\"nextSteps\":[\"Split the range into shorter intervals.\"],\"retryable\":false}}"
    }
  ]
}
```

Fai il parse del testo come JSON per ottenere:

| Campo | Significato |
| - | - |
| `code` | Uno dei codici sotto. Stabile; fai il branch su questo |
| `message` | Descrizione breve e sicura. Per `INVALID_INPUT` nomina il problema; per gli altri codici è una frase fissa |
| `nextSteps` | Istruzioni che un agente può seguire |
| `retryable` | Attualmente sempre `false`, consulta [Retry](#retry) |

Nient'altro del fallimento sottostante viene esposto: nessuna stack trace, SQL, risposte upstream o ID interni. Ogni richiesta viene loggata lato server con l'`x-request-id` echeggiato sulla risposta HTTP; citalo quando contatti il supporto.

## Codici

| Codice | Quando | Correzione tipica |
| - | - | - |
| `INVALID_INPUT` | Violazione dello schema, un intervallo di date superiore a 90 giorni, un timestamp di scrittura senza offset, `period` combinato con `from`/`to`, una query di statistiche a livello di account su un account multi-valuta | Correggi gli argomenti; `message` dice cosa è fallito |
| `PERMISSION_DENIED` | La credenziale non può agire su questo account | Verifica la key o il token |
| `NOT_FOUND` | Il locale, l'ordine, il menu o il link non esistono **su questo account**: le risorse su altri account sembrano identiche a quelle inesistenti | Chiama `list-venues` (o lo strumento list rilevante) e verifica l'ID |
| `CONFLICT` | Lo stato impedisce la scrittura, ad esempio un codice sconto già utilizzato in quel locale | Leggi lo stato attuale, poi decidi |
| `TIMEOUT` | Lo strumento ha superato i 30 secondi, o una chiamata upstream è andata in timeout | Restringi la query. Per una scrittura, **verifica lo stato prima di riprovare** |
| `UPSTREAM_UNAVAILABLE` | Una dipendenza (database, provider di pagamento) non è stata raggiunta | Attendi, poi riprova le letture; verifica lo stato prima di riprovare le scritture |
| `INTERNAL_ERROR` | Qualsiasi cosa inaspettata | Riprova le letture una volta; scrivi a [mcp@storekit.com](mailto:mcp@storekit.com) con il request ID se persiste |

## Retry

Le letture (`readOnlyHint: true`) sono sicure da riprovare dopo `TIMEOUT`, `UPSTREAM_UNAVAILABLE` o `INTERNAL_ERROR`, con backoff.

Le scritture sono diverse. `create-discount-code` e `create-payment-link` sono marcate `idempotentHint: false` e non hanno un idempotency key. Un `TIMEOUT` viene restituito quando il budget di 30 secondi si esaurisce, il che può accadere **dopo** che la riga è stata committata: il codice o il link potrebbero già esistere. Prima di riprovare una scrittura:

1. Chiama `list-discount-codes` e cerca il codice, oppure `list-payment-links` filtrato per locale e cerca il titolo/reference.
2. Richiama la scrittura solo se è assente.

Non riprovare mai le scritture automaticamente. È per questo che `retryable` è `false` su ogni codice oggi: il server non sa se la tua scrittura è andata a buon fine, quindi non ti dice di riprovare.

## Errori di validazione dal tuo client

Poiché gli errori non hanno `structuredContent`, i client conformi alla specifica (incluso l'SDK ufficiale TypeScript) saltano la validazione dell'output schema su di essi e mostrano l'envelope. Se il tuo client segnala invece un `-32602` o "structured content does not match schema", sta validando il *testo* contro l'`outputSchema` dello strumento; leggi direttamente il blocco di testo.


## Related topics

- [Formato della risposta](/docs/it/developers/mcp/response-format.md)
- [TISSL](/docs/it/guides/integrations/pos/tissl.md)
- [Iniezione degli ordini](/docs/it/guides/integrations/pos/order-injection.md)
- [Risoluzione dei problemi con i webhook](/docs/it/developers/webhooks/troubleshooting.md)
- [Video](/docs/it/guides/menu-engineering/videos.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.