Errors

Errors are structured JSON:

{ "error": "<code>", "message": "<human text>", "retry_after": <seconds> }

retry_after is present on 429s. On MCP the same failures arrive as readable tool results (isError: true with text), never as opaque protocol errors.

The table

HTTP	error	meaning
400	`bad_cursor`	malformed cursor — only ever page with a `next_cursor` you were handed
400	`bad_limit`	`limit` must be ≥ 1
400	`invalid_wallet`	a `0x…` string of the wrong hex length. It never falls through to name resolution.
400	`unknown_event_type`	an unrecognized value in `types`
401	`missing_credentials`	no `Authorization` header (`WWW-Authenticate: Bearer`)
401	`invalid_api_key`	unknown or revoked key
403	`depth_gated`	the market is past your history window (Basic Intelligence = 5 markets per trader)
403	`wallet_quota`	Basic Intelligence’s 3-distinct-wallets-per-UTC-day cap
404	`not_found`	no such market for this trader
404	`unknown_trader`	no resolvable wallet, URL, or name
404	`tape_not_found`	no such tape in your library
429	`rate_limited`	token bucket or per-minute ceiling hit
429	`daily_limit`	the paywall — Basic Intelligence’s daily call quota is spent
429	`monthly_limit`	the paywall — Pro / Max monthly call quota is spent
429	`busy`	heavy-read admission lane full
429	`too_many_auth_failures`	too many bad keys from your IP
503	`agent_api_disabled`	the agent surface is temporarily off
503	`archive_offline`	the archive is temporarily unreachable
503	`pm_offline`	Polymarket’s upstream is temporarily unreachable
504	`query_timeout`	the query was too broad (or `top-markets` `n` too large) — narrow and retry

How to react

Transient — wait and retry

rate_limited · busy · archive_offline · agent_api_disabledHonor Retry-After (seconds) where present. These clear in seconds. A well-behaved agent waits rather than failing the turn.pm_offline is a special case: the trader card and pnl-series degrade gracefully rather than erroring. The card serves with "polymarket": {"status": "pm_offline"} and carries the archive’s realized P/L as a labeled fallback. Use it, say which voice you are quoting, and move on.

The paywall — relay, do not retry

daily_limit · monthly_limitThe message is written to be relayed to your human. It names the upgrade and links https://polytape.io/pricing, and it is plan-aware (Pro is told about Max).Surface it and stop. retry_after on a daily cap points hours out and on a monthly cap points weeks out.

Plan walls — surface the upgrade

depth_gated · wallet_quotaNot outages. Retrying changes nothing — the answer will be identical until the plan changes or the day rolls over.

HTTP 403
{ "error": "wallet_quota",
  "message": "…names the plan, the upgrade, and the reset…",
  "used": 3,
  "limit": 3,
  "resets_at": "2026-07-29T00:00:00Z" }

resets_at is an ISO 8601 UTC string (next midnight UTC) — the one timestamp on this API that is not epoch seconds. There is no retry_after here.Treat depth_gated as an upgrade prompt, or as a not-found if you would rather not interrupt.

Your mistake — fix the input

bad_cursor · bad_limit · invalid_wallet · unknown_event_type · not_found · unknown_trader · tape_not_foundDo not retry the same request. Fix the argument.These burn a call (the counter charges served work), so validate before you fire — a typo’d condition_id costs a Basic user 1/50th of their day.

Credential trouble

missing_credentials · invalid_api_key · too_many_auth_failuresRevocation is instant, so a key that worked a minute ago can be dead now. Fix the credential, then wait out the auth-failure window before retrying.

Too broad

query_timeoutAlmost always a mega-maker (a 100k+ market account) plus a wide n on top-markets. Narrow n and retry — a small n is both cheaper and likelier to return.

What burns a call

Burns a call

Every successful GET or tool call. And application errors on real routes — 400, 403, 404, even 304.

Free

All 429 rejections. MCP protocol handshakes: connect, tools/list, prompts/list, fetching a prompt.

MCP error text

The same failures, as tool results:

Text	Underlying
`rate limit: retry in Ns`	`rate_limited` or `busy`
A message naming an upgrade and `polytape.io/pricing`	`daily_limit`, `monthly_limit`, or `wallet_quota`
`this market is outside your history window`	`depth_gated`
`no such market for this trader`	`not_found`
`no such tape in your library`	`tape_not_found`
`the trader archive is not available…`	`archive_offline`

MCP

REST

Reference

The table

How to react

What burns a call

Burns a call

Free

MCP error text

​The table

​How to react

​What burns a call

Burns a call

Free

​MCP error text

The table

How to react

What burns a call

MCP error text