Skip to main content

​
Problem responses

Errors use application/problem+json:
Common stable codes include: Raw RPC errors, stack traces, internal IDs, provider bodies, and secrets are never returned.

​
Weighted rate limits

Requests consume units: Configuration costs reflect whether a request needs live chain reads. Paginated reads scale with the requested page size: token lists use 2 units per 25 rows, activity and claim lists use 3 units per 25 rows, and holders use 10 units per 50 rows. 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. The same creator is limited to 1 per minute and 25 per day across all keys.
  • Post-launch token updates: covers name, symbol, public profile, and extra-metadata preparation. One key can prepare up to 10 updates per minute and 100 per day. The same token is limited to 2 per minute and 25 per day across all keys. Only update_profile uploads to IPFS.
  • 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 claim batches per minute. The same chain and caller are limited to 10 batches per minute across all keys; each batch contains 1 to 10 independent positions.
  • Creator actions: the same creator or metadata actor is limited to 20 announcement or metadata preparations per minute across all keys.
  • 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.
  • Profile metadata 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 update_profile, the operation that 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. 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.

​
Idempotency

Use Idempotency-Key for launch preparation and profile metadata preparation that pins content.
  • keys are scoped to the authenticated API key and route
  • the same key and same body replay the completed response
  • the same key with a different body returns idempotency_key_reused
  • an in-flight duplicate returns idempotency_in_progress

​
Retry policy

  • retry 429 after Retry-After
  • 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 profile-metadata 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.