Errors & limits

v2 shares the per-key rate limits, monthly quotas and error envelope with v1. This page covers the envelope once, then everything specific to v2.

Error envelopeCopy Anchor Link

Every non-2xx response is JSON with one error object:

{
  "error": {
    "_tag": "BadRequestError",
    "message": "Invalid mint",
    "details": { "code": "invalid_mint" }
  }
}

• _tag names the error class and maps to the HTTP status (table below).
• message is human-readable and may change; do not branch on it.
• details is optional. When present it is an object; stable machine-readable cases carry a details.code. Branch on _tag first, then details.code.
• Error responses are never cached (Cache-Control: no-store) and carry an x-request-id header.

Status codesCopy Anchor Link

The API sends no rate-limit headers and no Retry-After. On 429 and 5xx, back off exponentially with jitter (for example 250 ms, 500 ms, 1 s, 2 s, each plus up to 150 ms of jitter) and cap the attempts. Never retry 400, 401, 403 or 404 without changing the request.

What each status means on the v2 surfaces:

• 400 — invalid params or body, a list-mutation domain error, or a malformed multichain reference (unknown chain, bad address, address-shaped {assetId}). See the code tables below.
• 403 — insufficient scope, a list owned by another project, or a moderator-locked list.
• 404 — an unknown list slug, a draft or archived community list, or a member that is not in the list. The body is "List not found" with resource: "token_list" in every list case, so branch on the status, not the message. On the asset surface a 404 always carries a details.code (asset_not_found, variant_not_found).
• 429 — per-key throughput, monthly quota, or the provider lookup budget.

List mutation codes (details.code)Copy Anchor Link

Domain errors from list writes are 400 unless noted. The code is stable; the message is not.

Batch add (POST /v2/lists/{slug}/members) reports per-mint failures inside failed[] using the same codes instead of failing the whole call.

Multichain asset codes (details.code)Copy Anchor Link

Every 400 and 404 from /v2/chains, /v2/assets* and /v2/variants* carries a stable details.code; the extra details keys named below are there to build a message from.

limit and offset keep the platform-wide behaviour: a non-integer or limit=0 is a 400 without a details.code; a limit above the route's maximum is clamped, not rejected.

Provider lookup budgetCopy Anchor Link

Three endpoint groups can reach the live market-data provider for mints unknown to the index, so they share a per-key budget on top of the standard rate limits:

• Every call is charged, not every lookup; the API cannot know in advance how many mints will miss the local index. Within a batch call, at most about 50 unknown mints are resolved against the provider; the rest fail individually as unknown_mint and can be retried in a later batch.
• Exhausting a budget returns 429 with _tag: "RateLimitedError". There is no Retry-After; back off until the window resets (10 minutes by default) rather than retrying immediately.
• The budget is keyed per API key, not per project. Defaults are server-tunable and may be raised for a project on request.
• Identical search queries within the cache window (below) are served from cache and do not count.
• If the budget store is unavailable the check fails open; the per-call caps still bound cost.

Caching and stalenessCopy Anchor Link

Successful GET responses carry Cache-Control and may be served from an edge cache:

The registry routes have their own windows; see Registry endpoints.

The catalog, list detail and compose endpoints additionally keep a last-good copy: if the list backend is unavailable they return the most recent successful payload (up to 10 minutes old) with a 200 rather than a 5xx. Treat updatedAt as the freshness signal, and never cache a check-slug answer: a slug freed by a delete must read as available immediately.

The asset surface does the same per request shape: GET /v2/assets (15 min), GET /v2/assets/{assetId} (15 min), GET /v2/assets/{assetId}/variants (10 min) and GET /v2/variants/{chain}/{address} (15 min) serve the last healthy payload for the same params when the data layer is unavailable. A 404 is a real answer and is never kept as last-good. GET /v2/chains always serves its compiled metadata, with variantCount and assetCount as null when the counts cannot be read. Use market.lastFetchedAt and referenceMarket.asOf as the freshness signals.

Limits at a glanceCopy Anchor Link

Caps are enforced server-side and may change; branch on details.code, not on the numbers.