Rate Limits & Errors

This page is modeled after common API docs patterns: one place for limits, errors, and operational behavior.

Rate limits

Tokens API enforces per-key limits. If a key exceeds allowed throughput or quota, the API returns 429.

Practical guidance:

• Treat 429 as retryable.
• Use exponential backoff with jitter.
• Avoid unbounded parallel fan-out.
• Cache data where possible.

Quota behavior

Platform keys can also have monthly quotas. Exceeding quota also returns 429.

Error envelope

Platform endpoints use a stable error shape:

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

details is optional.

Common status codes

• 400 Bad request (invalid query/body/params)
• 401 Unauthorized (missing/invalid API key)
• 403 Forbidden (missing required scopes)
• 404 Not found (unknown resource or mapping)
• 429 Rate-limited or quota exceeded
• 500 Internal server error

Retry matrix

• Retry: 429, transient 5xx
• Do not retry without changes: 400, 401, 403, 404

TypeScript retry example

export async function fetchWithRetry(url: string, init: RequestInit, maxRetries = 4): Promise<Response> {
  let attempt = 0;

  while (true) {
    const res = await fetch(url, init);
    if (res.ok) return res;

    const retryable = res.status === 429 || (res.status >= 500 && res.status < 600);
    if (!retryable || attempt >= maxRetries) return res;

    const base = 250 * 2 ** attempt;
    const jitter = Math.floor(Math.random() * 150);
    await new Promise(resolve => setTimeout(resolve, base + jitter));
    attempt += 1;
  }
}