Skip to main content

​
Problem responses

Errors use application/problem+json:
type links to the exact code section on this page. code is the stable value for program logic, detail explains this occurrence, action gives the safe next step, and request_id identifies the request for support. Validation problems can also include invalid_parameters. Resource errors can include resource, chain_id, token_address, and suggested_endpoint. Balance errors can include asset, actual_raw, and required_raw. Raw RPC errors, stack traces, internal IDs, provider bodies, and secrets are never returned. Treat detail and action as human-readable text that may improve over time. Branch only on status and code.

​
Problem code reference

​
Request validation

  • invalid_request (400 or 413): the request, JSON transport, or body size is invalid. Correct the request using detail, then send it again.
  • unknown_parameter (400): one or more fields are not supported. Remove the fields listed in invalid_parameters.
  • duplicate_parameter (400): a query parameter was supplied more than once. Supply it once.
  • incompatible_parameters (400): individually valid parameters cannot be used together. Follow invalid_parameters and suggested_endpoint when present.
  • invalid_parameter (400): one or more fields have invalid values or formats. Correct the fields listed in invalid_parameters.
  • missing_idempotency_key (400): an operation that can create off-chain work needs Idempotency-Key. Send a new random UUID.
  • invalid_idempotency_key (400): the retry ID is empty or too long. Send 1 to 255 characters.

​
Authentication and authorization

  • missing_api_key (401): x-api-key is absent. Send an active API key in that header.
  • invalid_api_key (401): the key is malformed, inactive, revoked, expired, or does not verify. Use an active key or create a replacement.
  • origin_not_allowed (403): the browser origin is not allowed by the key. Use an allowed origin or update the key’s origin restrictions.
  • insufficient_scope (403): the key lacks the scope named in detail. Use a key with that scope.
  • wallet_not_authorized (403): the wallet does not own the required role, quote, claim, or resource. Use the authorized wallet.

​
Resources and current state

  • not_found (404): the tracked resource or API operation does not exist. Verify the chain and identifier, use suggested_endpoint when present, and do not continuously retry an unchanged 404.
  • stale_plan (409): a transaction plan expired or its chain configuration changed. Prepare a new plan before signing or broadcasting.
  • stale_quote (409): the quote expired or current execution state moved outside its reviewed limits. Request and review a fresh quote.
  • salt_unavailable (409): the prepared launch salt is already used. Prepare the launch again for a new salt and token address.
  • invalid_permit (409): Permit2 state changed or the signature no longer matches. Request a fresh quote, sign its current data, and prepare again.
  • approval_not_confirmed (409): the required token approval is not confirmed on-chain. Confirm it, then prepare again.
  • announcement_id_conflict (409): the generated announcement identifier is already used. Prepare again for a new identifier.
  • cursor_filter_mismatch (409): the cursor belongs to another route or filter set. Restart without a cursor and keep the same route and filters on later pages.
  • cursor_stale (409): the resource ordering changed after the cursor was issued. Restart from the first page.
  • idempotency_in_progress (409): an identical request is still running. Wait briefly, then retry the exact request with the same key.
  • nothing_to_claim (409): the requested position currently has no claimable value. Refresh the wallet’s claim positions after state changes.

​
Unsupported or non-executable requests

  • unsupported_operation (422): the resource, suite, quote, or operation is not supported. Read /config and use a supported combination.
  • unsupported_chain (422): the chain is not supported. Use Base 8453 or Robinhood 4663.
  • idempotency_key_reused (422): the retry ID was already used with different input. Generate a new UUID.
  • invalid_amount (422): the amount is invalid for the requested operation or current wallet state. Correct it using detail.
  • invalid_referrer (422): the referrer is reserved, duplicated, or otherwise ineligible. Remove it or use a separate eligible wallet.
  • invalid_allocation (422): launch allocations violate the supported bounds. Correct the field in invalid_parameters.
  • invalid_vesting (422): the vesting schedule violates the supported timing, step, or cumulative-allocation rules. Correct the field in invalid_parameters.
  • insufficient_balance (422): the wallet cannot fund the requested operation. Fund at least required_raw of asset, then prepare again.
  • quote_unavailable (422): no safe executable quote exists for the token, side, amount, or current pool state. Correct the input or retry after market state changes.
  • simulation_failed (422): the unsigned transaction did not simulate successfully. Resolve the condition in detail, then prepare again.

​
Limits and service failures

  • rate_limit_exceeded (429): the API key exceeded a weighted burst, minute, day, or month limit. Wait for Retry-After.
  • quota_exceeded (429): a key, wallet, token, creator, source, service, or concurrency safety ceiling was reached. Wait for Retry-After and reduce frequency or concurrency.
  • internal_error (500): an unexpected server fault occurred. Retry once; if it persists, contact support with request_id.
  • upstream_error (502): a required chain, metadata, indexer, holder, or internal origin dependency returned an invalid response. Retry with capped exponential backoff and jitter.
  • temporarily_unavailable (503): a required service or verified live state is unavailable. Retry with capped exponential backoff and jitter.
  • upstream_timeout (504): a required dependency timed out. Retry with capped exponential backoff and jitter.

​
Weighted rate limits

GET /health and browser preflight requests do not consume API-key units. Every other operation is authenticated and metered against the calling key. A successful preflight only confirms browser transport; the following API request must still pass API-key, scope, origin, validation, and rate-limit checks. Requests consume units: Configuration costs reflect whether a request needs live chain reads. Paginated reads scale with the requested page size: token lists, search, creator lists, and announcements use 2 units per 25 rows; trades, wallet activity, fee claims, and vesting use 3 units per 25 rows; holders use 10 units per 50 rows. Claim batches scale by position, so 10 prepared claims cost 30 units. For example, GET /tokens?limit=100 costs 8 units and a 200-holder page costs 40 units. Initial plans: Additional safety ceilings apply before expensive work begins:
  • Launch preparation: protects the complete launch workflow, including live configuration reads, Pinata uploads, 01 address mining, calldata construction, and simulation. One key can prepare up to 3 launches per minute and 100 per day. Within that key, the same creator is limited to 1 per minute and 25 per day; a different key cannot consume the counter.
  • Metadata documents: the IPFS document route allows up to 10 preparations per key each minute and 100 per day. Within that key, the same token is limited to 2 per minute and 25 per day. Name, symbol, and extra-metadata preparation does not use these pinning caps.
  • Trading: the same wallet can request up to 60 swap quotes and 30 swap preparations per minute across all keys.
  • Claims: one key can prepare up to 20 fee and vesting batches combined per minute. The same chain and caller are limited to 10 combined batches per minute across all keys; each batch contains 1 to 10 independent positions.
  • Creator actions: within each key, the same creator or metadata actor is limited to 20 announcement or metadata preparations per minute.
  • Holder protection: holder snapshots allow 2 concurrent requests per key.
Shared safeguards stop fresh-key cycling without changing ordinary use:
  • Authentication: uncached key-prefix lookups allow 60 requests per source each minute. Valid authorization metadata is cached for at most 5 seconds, and an unknown prefix for 2 seconds, so repeated invalid keys cannot turn Convex into an unbounded lookup service.
  • Live configuration: 15 requests per source and 120 across the service each minute, with 10 in flight.
  • Holder snapshots: 60 requests per source and 300 across the service each minute, with 20 in flight.
  • Launch workflow: 6 requests per source each minute and 200 per day; 60 across the service each minute and 2,000 per day.
  • Metadata-document pinning: 20 requests per source each minute and 500 per day; 120 across the service each minute and 5,000 per day. These limits apply only to the document preparation route, which can upload content.
  • All live transaction preparation: 120 requests per source and 1,000 across the service each minute, with 50 preparations in flight.
New keys use the Developer limits. Higher limits are reviewed per key, and Partner access uses a custom per-key policy. Responses include RateLimit, RateLimit-Policy, X-RateLimit-*, and X-Request-Id. A 429 includes Retry-After. Compatibility routes also expose Deprecation and Link headers. These headers do not change route behavior; follow the linked migration guide for the focused replacement. Limits are enforced atomically in a separately managed Redis service. Durable hourly and daily usage summaries are stored in the API-owned usage table in Convex. Operators can assign a bounded per-key policy override, including a custom Partner policy, without creating another policy table.

​
Safe request retries

Mintlify labels this as Unique retry ID. Send it in the standard Idempotency-Key header. Generate a random UUID for each new launch or metadata-document update, then reuse it only when retrying that exact request.
  • it can contain 1 to 255 characters and is kept for 24 hours
  • the same API key, retry ID, and body replay the completed response
  • using the same retry ID for different input returns idempotency_key_reused; the second request is not prepared
  • different API keys may safely use the same retry ID

​
Retry policy

  • retry 429 after Retry-After
  • retry 500 once; if it persists, contact support with the request_id
  • retry 502, 503, and 504 with capped exponential backoff and jitter
  • do not blindly retry 400, 401, 403, or 422
  • prepare again after stale_plan
  • restart pagination after a stale or filter-mismatched cursor
  • never broadcast a transaction after its expiry

​
Caching and data freshness

Each response includes meta.generated_at, which records when the gateway formed the response. Source freshness comes from resource-level updated_at, observed or confirmed block, and finality fields. Configuration exposes as_of_block whenever suites or quotes require a live one-block chain read. Every request admitted by the weighted limiter consumes its documented route weight, including an idempotent replay or an internal Convex query-cache hit. Units measure access to the operation, not the gateway’s internal compute cost. With a valid key, insufficient-scope and oversized-page rejections consume the route’s base weight. Missing or invalid authentication, body-size enforcement, and requests rejected by an already-exhausted quota record zero units. A request that passes the limiter and later fails endpoint validation, simulation, or an upstream dependency consumes the route weight because execution capacity was reserved. The gateway does not keep a second TTL snapshot of product responses. Convex-backed reads use Convex’s dependency-aware query cache, so a database change invalidates the affected query result without waiting for a gateway TTL. Ranked and trending values still follow the existing materialized-view refresh schedule shown by their updated_at field. Live configuration, swap quotes, wallet balances, allowances, claims, transaction plans, and simulations are never response-cached. External holder pages are requested from their provider without a stale fallback. If a required dependency is unavailable, the API returns a mapped error instead of silently returning an older snapshot. Redis is still used for short-lived API-key authorization metadata, rate counters, concurrency, idempotency, leases, and usage aggregation. Exact idempotent launch and metadata-document retries may replay their original response to avoid duplicate Pinata and simulation work, but that response is scoped to the same API key, idempotency key, route, and request body. Use a new idempotency key after a returned plan expires.