Limits | JoyToken | Documentation

JoyToken’s current public limits come from API key quota, key policy, and wallet balance precheck. Do not assume fixed QPS, RPM, or TPM quotas.

Current Limits

Limit	Source	Result
Daily quota	API key budget	`402 insufficient_quota`
Weekly quota	API key budget	`402 insufficient_quota`
Wallet balance	Personal or organization wallet	`402 insufficient_quota`
Model blacklist	API key policy	`403 policy_rejected`
Tier allowlist	API key policy and request `tier`	`403 policy_rejected`
IP allowlist/blocklist	API key policy	`403 policy_rejected`

Tier Fallback

Every request must include model: "auto"; when the current tier lacks balance, JoyToken may try another tier allowed by policy.

Current tier	Fallback order
`premium`	`standard` -> `economy`
`standard`	`premium` -> `economy`
`economy`	`standard` -> `premium`

Requests always use model: "auto"; when no eligible candidate remains after policy, tier, wallet, and budget filters, the request fails instead of selecting a caller-specified model.

Client Handling

Error	Retry?	Fix
`400`	No	Fix request body
`401`	No	Add API key
`402`	No	Top up or adjust key budget
`403`	No	Adjust policy, IP, tier, or model
`502`	Short backoff	Could be routing or upstream temporary failure
`503` / `504`	Yes	Use exponential backoff

Exponential Backoff

const retryableStatuses = new Set([502, 503, 504]);
export async function withJoyTokenRetry<T>(fn: () => Promise<T>, attempts = 3) {
  let lastError: unknown;
  for (let attempt = 0; attempt < attempts; attempt += 1) {
    try {
      return await fn();
    } catch (error: any) {
      lastError = error;
      const status = error?.status ?? error?.response?.status;
      if (!retryableStatuses.has(status) || attempt === attempts - 1) throw error;
      await new Promise((resolve) => setTimeout(resolve, 300 * 2 ** attempt));
    }
  }
  throw lastError;
}