Rate limits and errors

All partner reads share these limits:

Window	Requests	Reset
Minute	300	Next fixed minute boundary
Day	50,000	00:00 UTC

Both limits apply to the partner, across all its keys, endpoints, IP addresses, and app instances. These are fixed windows, not a guaranteed requests-per-second allowance. Creating a replacement key does not reset either counter.

Every authorized read that reaches the partner limiter spends the shared request budget before routing. HEAD counts, and a later validation error, 404, or endpoint-level refusal does not refund that request. Browser OPTIONS preflights do not spend this authenticated read budget.

Additional endpoint/IP limits and edge protections also apply. Key lookups and browser preflights have a separate 600/minute per-IP, per-app-instance limit. You can therefore receive 429 before your partner quota is exhausted; the partner quota is not a reservation of capacity. An unavailable key or rate-limit service refuses requests instead of allowing unlimited access.

Retry behavior

On 429, honor Retry-After (seconds) when present. A partner-quota refusal includes this header. Wait at least that long and add random jitter to avoid synchronized retries. Endpoint or upstream refusals can have different error codes and may omit the header; use bounded exponential backoff in that case.

Coming-soon endpoints: discovery, holders, launch activity, pool summaries, candles, and trades currently return 503 because launchpad indexing is not enabled. Do not poll these endpoints until availability is announced, even if a response includes Retry-After. Their contracts and examples are readable now.

For temporary 502 or 503 responses, also honor Retry-After when present. Limit retries and show an unavailable state after repeated failures. Do not retry 400, 401, 403, 404, or 405 in a tight loop; fix the request, key, origin, or availability issue first.

function retryDelayMs(response, attempt) {
  if (![429, 502, 503].includes(response.status)) return null;
  if (attempt >= 3) return null;
  const value = response.headers.get('retry-after');
  const seconds = value !== null && /^\d+$/.test(value) ? Number(value) : null;
  const base = seconds !== null
    ? seconds * 1000
    : Math.min(30_000, 1000 * 2 ** attempt);
  return base + Math.floor(Math.random() * 1000);
}

Use the returned delay to schedule a later request. A daily-quota delay may be many hours: do not hold a user-facing HTTP request open while waiting. Reuse recent data with an appropriate freshness label, batch supported price queries, and coalesce concurrent identical requests on your backend. Remaining-quota and reset headers are not part of this API contract.

Authentication and quota errors

Partner access errors use this JSON envelope:

{
  "error": {
    "code": "partner_key_invalid",
    "message": "A valid partner API key is required."
  }
}

HTTP status	Code	Action
401	partner_key_invalid	Check the complete key and header. The key may be malformed, unknown, or revoked. Contact Blast for a replacement.
403	partner_read_forbidden	Use an endpoint from the read reference.
403	partner_origin_forbidden	Ask Blast to register the exact browser origin and use a key for that partner. Check the preflight headers.
405	partner_read_only	Use GET or HEAD.
429	partner_rate_limited	The partner or key-lookup IP limit was reached. Respect Retry-After.
503	partner_api_unavailable	Key verification or rate-limit storage is unavailable. Retry later.

A missing partner header follows the ordinary website access rules and can return a different 401 code. Send the header on every API call. HEAD responses and browser-blocked CORS failures do not expose a JSON error body.

Endpoint errors and unavailable data

Endpoint errors retain their own codes, including invalid_parameter, not_found, rate_limited, and service_unavailable. Launchpad errors may use codes such as LAUNCHPAD_QUERY_INVALID or LAUNCHPAD_RATE_LIMITED. Handle HTTP status first, then use the code for a more specific message.

An unknown resource or unsupported venue/route combination can return 404 with a valid key. Check the resource ID and supported routes. Partner read access is independent of the frontend’s launch status; an invalid or revoked key returns 401.

Discovery and search also represent failures inside section objects. A 200 search response can contain an unavailable group while other groups are readable. Render each section according to its state; do not replace unavailable data with an empty list or zero. A 503 can contain sections instead of the error envelope above.