API rate limits
These are the limits the /api/v1 handlers enforce. A number that an environment variable can replace is the default. The response headers report the limiter that actually ran. They are not a second copy of this page.
Requests per key
Each API key has its own request counter. bump_api_rate_limit stores that counter in a fixed clock minute (date_trunc of the current minute). The window is 60 seconds. The policy name is api-key.
A human key defaults to 60 requests per minute. API_RATE_LIMIT_PER_MINUTE can replace that default. A missing value, a non-numeric value, or a value outside 1 to 10000 keeps 60. A human key has no hourly Script to audio job cap. A signed-in access token uses the same number, stored by bump_session_rate_limit. The policy name is api-session. That counter is not the key's counter. Apply supabase/migrations/034_show_topics_and_session_rate.sql before a session can be counted. API keys keep using bump_api_rate_limit.
An agent key uses its trust tier. A requests_per_minute or jobs_per_hour value stored on the agent account replaces that tier field. The tier defaults are:
- new: 10 requests per minute. jobs_per_hour is 0, so creating a Script to audio job is refused before the hourly job counter runs.
- funded: 10 requests per minute and 5 Script to audio jobs per hour.
- verified: 30 requests per minute and 30 Script to audio jobs per hour.
- claimed: 60 requests per minute and no hourly Script to audio job cap.
Script to audio jobs
Job creation is counted per account, on user id, for script_jobs created in the last 3600 seconds. It is not counted per API key. The policy name is script-jobs. The cap is the account's jobs_per_hour. When that value is null, or 0, this limiter is not evaluated. A script that exceeds the account word limit is rejected first, and that response does not include this policy. A funded account defaults to 5 jobs per hour. A verified account defaults to 30.
A key whose account email is on ADMIN_EMAILS does not evaluate the hourly job cap, the daily spend cap, or the account word cap. The per-key requests-per-minute cap still applies. POST /api/v1/script-audio for that key does not add the script-jobs policy.
Verification emails
POST /api/v1/agent-accounts/verify-email can send 5 codes per account per 3600 seconds. The count is rows in agent_email_codes for that account in the sliding hour. This number is the EMAIL_SENDS_PER_HOUR constant, not an environment variable. The policy name is verification-emails. Submitting a code on the same route does not evaluate this send cap.
Signup per IP
Challenge requests and account-creation attempts use bump_agent_signup_rate, one fixed bucket per IP hash. A window shorter than 60 seconds is stored as 3600 seconds. A window longer than 604800 seconds is stored as 604800 seconds. The defaults sit inside that range. Created accounts use a separate sliding count of agent_accounts for that IP hash. The defaults are:
- Challenges: 10 requests per 3600 seconds. AGENT_SIGNUP_CHALLENGE_IP_LIMIT and AGENT_SIGNUP_CHALLENGE_WINDOW_SEC can replace the defaults. The policy name is signup-challenges.
- Signup attempts: 10 requests per 3600 seconds, in a different bucket from challenges. AGENT_SIGNUP_ATTEMPT_IP_LIMIT and AGENT_SIGNUP_ATTEMPT_WINDOW_SEC can replace the defaults. The policy name is signup-attempts.
- Accounts created: 3 accounts per 86400 seconds. AGENT_SIGNUP_ACCOUNT_IP_LIMIT and AGENT_SIGNUP_ACCOUNT_WINDOW_SEC can replace the defaults. The policy name is signup-accounts.
Headers
A response that evaluated a limiter sends X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Reset is the Unix epoch second when that window resets. It also sends RateLimit-Policy and RateLimit. Policy is the quoted name, q for the limit, and w for the window in seconds. RateLimit is the quoted name, r for remaining, and t for seconds until reset. When more than one policy was evaluated, those two headers list every policy. X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After describe the first exhausted policy, or the first policy when none is exhausted.
Retry-After is sent only on 429, and only in seconds. The API does not set CORS headers, so it does not list these names in Access-Control-Expose-Headers.
Which responses include them
Authenticated /api/v1 routes include the api-key policy after bump_api_rate_limit runs, on success and on later errors from that same request. POST /api/v1/script-audio adds script-jobs when that quota is evaluated. The verify-email send path adds verification-emails after that count runs. POST /api/v1/agent-accounts/challenge includes signup-challenges after that check. POST /api/v1/agent-accounts includes signup-attempts after that check, and signup-accounts after the account-cap query succeeds. POST /api/v1/credits/pay adds machine-topups after the api-key check. That window is 5 attempts per minute. A 402 payment challenge counts.
These responses do not include the headers, because no limiter ran: GET /api/v1, POST /api/v1, an unknown /api/v1 path, and an unsupported method. A 401 for a missing, invalid, revoked, or expired key does not include them. A 403 for a frozen account or an insufficient scope, when that check happens before the counter, does not include them. A 500 or 503 from the rate-limit RPC does not include them.
Handling 429
Wait the number of seconds in Retry-After, then send the request again. Do not retry before that delay. X-RateLimit-Reset is the Unix time when the window that rejected the request resets. The problem body can also include retry_after_sec for the same wait. Per-key rejection uses rate_limit_exceeded. An hourly job rejection uses job_rate_limited. Signup rejection uses signup_rate_limited. A verification-email rejection uses rate_limit_exceeded.
Daily spend caps and daily pack caps are account limits. They are not these request windows. Read the developer docs, the API changelog, and the API versioning and deprecation policy.
