Fehler

Fehler treten auf zwei Ebenen auf. Probleme mit Authentifizierung, Origin und Rate-Limit werden vor MCP als reine HTTP-Antworten abgewiesen. Alles, was innerhalb eines Tool-Aufrufs passiert, kommt als MCP-Tool-Ergebnis mit isError: true zurück.

HTTP-Level

Status	Ursache	Body
`401`	Fehlende oder ungültige Zugangsdaten	`WWW-Authenticate: Bearer realm="OAuth", resource_metadata="…"`-Header; OAuth-Discovery starten
`403`	`Origin`-Header nicht auf der Allow-List	`{ "error": "Origin not allowed" }`
`429`	Mehr als 60 Anfragen in einer Minute für diesen Benutzer oder Schlüssel	`{ "error": "Rate limit exceeded" }` mit `Retry-After` in Sekunden

Diese liegen außerhalb des MCP-Envelopes; eine MCP-Client-Bibliothek wirft sie typischerweise als Transport-Fehler.

Tool-Fehler

Ein fehlgeschlagener Tool-Aufruf ist ein normaler JSON-RPC-Erfolg, dessen Ergebnis isError: true, einen einzelnen Text-Block und kein structuredContent hat:

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

Parsen Sie den Text als JSON, um zu erhalten:

Feld	Bedeutung
`code`	Einer der Codes unten. Stabil; verzweigen Sie darauf
`message`	Kurze, sichere Beschreibung. Für `INVALID_INPUT` benennt sie das Problem; für andere Codes ist sie eine feste Formulierung
`nextSteps`	Anweisungen, denen ein Agent folgen kann
`retryable`	Derzeit immer `false` — siehe Retrying

Nichts anderes vom zugrundeliegenden Fehler wird offengelegt: keine Stack Traces, kein SQL, keine Upstream-Antworten oder interne IDs. Jede Anfrage wird serverseitig mit der x-request-id protokolliert, die auf der HTTP-Antwort mitgegeben wird; nennen Sie diese, wenn Sie den Support kontaktieren.

Codes

Code	Wann	Typische Lösung
`INVALID_INPUT`	Schema-Verletzung, ein Datumsbereich über 90 Tage, ein Write-Zeitstempel ohne Offset, `period` kombiniert mit `from`/`to`, eine kontoweite Statistik-Abfrage auf einem Konto mit mehreren Währungen	Argumente korrigieren; `message` sagt, was fehlgeschlagen ist
`PERMISSION_DENIED`	Die Zugangsdaten dürfen auf diesem Konto nicht handeln	Schlüssel oder Token prüfen
`NOT_FOUND`	Die Filiale, Bestellung, das Menü oder der Link existiert auf diesem Konto nicht — Ressourcen auf anderen Konten sehen identisch aus wie nicht existierende	`list-venues` (oder das relevante List-Tool) aufrufen und die ID prüfen
`CONFLICT`	Ein Zustand verhindert den Write, z. B. ein Rabattcode, der bei dieser Filiale bereits verwendet wird	Aktuellen Zustand lesen, dann entscheiden
`TIMEOUT`	Das Tool überschritt 30 Sekunden, oder ein Upstream-Aufruf lief in ein Timeout	Anfrage einengen. Bei einem Write: Zustand vor dem Retry prüfen
`UPSTREAM_UNAVAILABLE`	Eine Abhängigkeit (Datenbank, Zahlungsanbieter) konnte nicht erreicht werden	Warten, dann Reads erneut versuchen; Zustand vor dem Retry von Writes prüfen
`INTERNAL_ERROR`	Alles Unerwartete	Reads einmal erneut versuchen; bei anhaltendem Problem mcp@storekit.com mit der Request-ID kontaktieren

Retrying

Reads (readOnlyHint: true) können nach TIMEOUT, UPSTREAM_UNAVAILABLE oder INTERNAL_ERROR mit Backoff sicher erneut versucht werden. Writes sind anders. create-discount-code und create-payment-link sind mit idempotentHint: false markiert und haben keinen Idempotenz-Schlüssel. Ein TIMEOUT wird zurückgegeben, wenn das 30-Sekunden-Budget aufgebraucht ist. Das kann nach dem Commit der Zeile passieren — der Code oder Link kann bereits existieren. Bevor Sie einen Write erneut versuchen:

list-discount-codes und nach dem Code suchen, oder list-payment-links nach Filiale gefiltert und nach dem Titel/der Referenz suchen.
Den Write nur erneut aufrufen, wenn er fehlt.

Führen Sie Writes niemals automatisch erneut aus. Deshalb ist retryable heute bei jedem Code false: Der Server weiß nicht, ob Ihr Write angekommen ist, also sagt er Ihnen nicht, dass Sie es erneut versuchen sollen.

Validierungsfehler von Ihrem Client

Da Fehler kein structuredContent tragen, überspringen spec-konforme Clients (einschließlich des offiziellen TypeScript-SDK) die Output-Schema-Validierung darauf und zeigen den Envelope. Wenn Ihr Client stattdessen einen -32602 oder „structured content does not match schema”-Fehler meldet, validiert er den Text gegen das outputSchema des Tools; lesen Sie den Text-Block direkt.

Developers

Guides

Ordering Agents

Merchant MCP

Webhooks

HTTP-Level

Tool-Fehler

Codes

Retrying

Validierungsfehler von Ihrem Client

​HTTP-Level

​Tool-Fehler

​Codes

​Retrying

​Validierungsfehler von Ihrem Client

HTTP-Level

Tool-Fehler

Codes

Retrying

Validierungsfehler von Ihrem Client