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

# Fehler

> Wie das Merchant MCP Fehler meldet: HTTP-Abweisungen, isError-Tool-Ergebnisse mit stabilen Codes und Retry-Regeln für Writes im Timeout.

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:

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

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](#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](mailto: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:

1. `list-discount-codes` und nach dem Code suchen, oder `list-payment-links` nach Filiale gefiltert und nach dem Titel/der Referenz suchen.
2. 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.


## Related topics

- [Fehlerbehebung](/docs/de/guides/integrations/pos/comtrex/troubleshooting.md)
- [Fehlerbehebung bei Webhooks](/docs/de/developers/webhooks/troubleshooting.md)
- [PointOne Fehlerbehebung](/docs/de/guides/integrations/pos/pointone/troubleshooting.md)
- [Lightspeed Fehlerbehebung](/docs/de/guides/integrations/pos/lightspeed/troubleshooting.md)
- [Syrve Fehlerbehebung](/docs/de/guides/integrations/pos/syrve/troubleshooting.md)


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