KLAIM Amsterdam API errors and rate limits

KLAIM Amsterdam's native Shopify MCP service uses JSON-RPC 2.0. Inspect the JSON body even when HTTP status is 200: an error member means the request failed.

Structured MCP errors

Errors include a numeric error.code, a human-readable error.message, and, when applicable, machine-readable error.data. For example, a missing agent profile can return error.data.code: invalid_profile_url. Provide a reachable, compatible UCP agent profile and use the latest tool schema. A continue_url is a handoff instruction, not confirmation that the action succeeded.

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "UCP discovery failed",
    "data": { "code": "invalid_profile_url" }
  }
}

Missing resources

A missing product or page is a Not Found error. Check the URL against the sitemap and do not treat it as evidence that an entire collection or store is unavailable.

HTTP failures and retries

  • 400: correct the request body or parameters.
  • 401 or 403: verify the provider credential, agent identification and required permission. Do not retry with broader access automatically.
  • 404: check the product handle or discovery URL against the sitemap.
  • 429: honor Retry-After when present and use exponential backoff.
  • 5xx: back off; verify the outcome before retrying a shopping mutation.

Shopify's public product endpoint can return an empty 404 body. Handle status before parsing JSON. The storefront's Markdown negotiation and its native MCP resource advertisement are controlled by Shopify; do not assume that every failure route returns a structured body.

Back to KLAIM Amsterdam developer documentation · Authentication

KLAIM read-only API errors

The companion read-only API returns RFC 9457 application/problem+json errors with code, detail and resolution. Invalid/revoked/expired keys return 401; insufficient scopes or a mismatched environment return 403; missing products return 404; quota limits return 429 with Retry-After; unavailable catalog providers return 502. The disconnected sandbox never calls Shopify. Its MCP endpoint returns JSON-RPC protocol errors or tool errors according to MCP.