Error handling

The MCP Server handles errors gracefully and returns clear messages to your AI assistant, which then explains them to you in plain language. This page covers what can go wrong and how to troubleshoot.

Authentication errors

Error Cause Fix
"Missing X-Snipcart-Api-Key header" No API key was sent with the request Add the X-Snipcart-Api-Key header to your MCP server configuration
"Invalid API key" The API key is incorrect or revoked Check that your key matches the one in Dashboard → Account → API Keys
"Forbidden" Your API key lacks permission for this action Verify you're using the correct key type (test vs. live)

Rate limiting

The MCP Server enforces rate limits at two levels to protect your store and the Snipcart API.

Global rate limits

Limit Default Description
Requests per minute 100 Sliding window per API key
Concurrent requests 10 Maximum in-flight requests per API key

When the global rate limit is exceeded, requests return a 429 status with a retryAfter value. Most MCP clients will automatically wait and retry.

When the concurrency limit is exceeded, requests return a 503 status. This means too many requests are being processed simultaneously — the client will retry after a short pause.

Per-tool rate limits

Some tools have additional limits to match Snipcart's own enforcement:

Tool Limit
create_order_notification 20 calls per 2 minutes
list_discounts 10 calls per minute

Snipcart API rate limits

If the Snipcart API itself returns a 429 (too many requests), the MCP Server automatically retries up to 2 times with exponential backoff (up to 30 seconds wait). You don't need to do anything — this is handled transparently.

Common errors

Resource not found (404)

The order, customer, product, or other resource you referenced doesn't exist. Double-check the ID or token. Common causes:

  • Typo in the identifier
  • The resource was deleted
  • Using a test-mode API key to access live-mode data (or vice versa)

Bad request (400)

The parameters sent to the Snipcart API were invalid. This usually means:

  • A required field was missing (e.g., creating a coupon discount without a code)
  • A value was out of range (e.g., a rate greater than 1)
  • An invalid combination of trigger and type on a discount

Conflict (409)

The operation can't be completed because of a conflict. For example:

  • Trying to delete a discount that has been used in completed orders

Request timed out (408)

The Snipcart API took too long to respond. This can happen with:

  • Very large stores (100k+ orders)
  • Complex queries with broad date ranges

If you're self-hosting, increase the SNIPCART_TIMEOUT_MS environment variable.

Refund exceeds order total

You'll see this when trying to refund more than the order's total value. Check the order total first with get_order, then create the refund with the correct amount.

Response format

All tool responses follow a consistent structure.

Single item:

{
  "item": { ... }
}

Paginated list (offset-based):

{
  "items": [ ... ],
  "pagination": {
    "total": 100,
    "offset": 0,
    "limit": 20,
    "hasMore": true,
    "nextOffset": 20
  }
}

Paginated list (continuation token):

{
  "items": [ ... ],
  "pagination": {
    "hasMore": true,
    "continuationToken": "abc123xyz",
    "total": null
  }
}

Error:

{
  "isError": true,
  "error": "Human-readable error message"
}

In practice, your AI assistant interprets these responses for you — you'll see plain language summaries, not raw JSON.

Getting help

If you run into an issue that isn't covered here:

  • Check that you're using the correct API key (test vs. live mode)
  • Try the same operation in the Snipcart dashboard to confirm the resource exists
  • For self-hosted instances, check the server logs for detailed error information
  • Drop us a line at geeks@snipcart.com

Was this article helpful?