Errors and limits

A paid call without a key returns HTTP 401. A key whose account has no subscription to that listing returns HTTP 403.

Status codes

401: No API key was sent, or the key was not recognised.; What to do: Stop and ask the human for an IntelClaw API key (any account can create one free at /dashboard/keys). Retry with Authorization: Bearer im_…. Meanwhile the free sample and discovery reads still work.
403: The key is valid, but its account has no subscription to this listing, or a metered plan used its monthly cap.; What to do: Do not retry. Tell the human which listing needs a plan and link /checkout?listing={slug}. Keep using ?sample=1 if a sample is enough.
429: Rate limited.; What to do: Wait for the Retry-After header (seconds), then retry once. Don't hammer.
404: No live listing has that slug.; What to do: Re-read the catalog (GET /api/catalog) and use a current slug.
502: The listing's source is temporarily unavailable. Error responses are never counted as paid use.; What to do: Retry later with backoff. Check /status for the listing's latest health check.
503: The access check could not run. Paid data is never served when that happens.; What to do: Retry shortly. The body links the free sample.

Metered plans cap at 10,000 calls a month; calls past the cap return 403. The Live Price Feed plan has no monthly cap.

Error body

Errors are JSON with an error string. 401 adds hint, sample and discovery links. 429 sets Retry-After (seconds).

401 body

{
  "error": "A Polar API key is required.",
  "hint": "Subscribe with Polar, then send Authorization: Bearer im_...",
  "sample": "/api/v1/resources/{slug}?sample=1",
  "discovery": "/api/v1/resources/{slug}?discovery=1"
}

429 response

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0

{ "error": "Rate limit exceeded", "retryAfterSec": 12 }

502 body

{
  "ok": false,
  "error": "Origin resource unavailable",
  "detail": "…",
  "meta": { "source": "origin_error", "bodySha256": "…" }
}

MCP error codes

-32001 payment required: data.httpStatus is 401 (no key) or 403 (no subscription to that listing).
-32029 rate limited: HTTP 429 with Retry-After.
-32700 / -32600 parse or invalid request: HTTP 400.
-32601 method not found, -32602 invalid params, -32603 internal error.

Rate limits

Without a key: 60 requests per minute. With a key: 120 requests per minute per listing. Metered plans include 10,000 calls a month; calls past the cap return HTTP 403. The Live Price Feed plan has no monthly cap.

Responses carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

Stuck? Contact support. Billing and refunds: pricing FAQ.

Errors and limits

Command palette