Errori

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:

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

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 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:

Chiama list-discount-codes e cerca il codice, oppure list-payment-links filtrato per locale e cerca il titolo/reference.
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.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

Livello HTTP

Errori dello strumento

Codici

Retry

Errori di validazione dal tuo client

​Livello HTTP

​Errori dello strumento

​Codici

​Retry

​Errori di validazione dal tuo client

Livello HTTP

Errori dello strumento

Codici

Retry

Errori di validazione dal tuo client