API 參考文件僅提供英文版。
指南
Rate limits and retries
Two kinds of limit apply to every call: your plan's allowance, counted per account, and a flood limit, counted per address before your key is read.
Your plan's allowance
Your plan sets how many requests an account may make each day and each UTC month, and how many verifications each day and each billing period. Every answer to an admitted request, and every allowance 429, reports where you stand in RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-Calls-Remaining, X-Verifications-Remaining and X-Quota-Reset; the reference overview describes each one.
When an allowance is spent the call answers 429 with code quota-exhausted, is not charged, and says in Retry-After how many seconds until the allowance resets (a daily one at midnight UTC). A request allowance names the limit reached in message; a verification allowance names it in metadata.boundBy (DAILY_VERIFICATIONS or MONTHLY_VERIFICATIONS).
Extra verifications past your plan's allowance stop at the spending limit you set in the console's Billing section. Reaching it answers 429 quota-exhausted with metadata.boundBy SPEND_CEILING, Retry-After set to the seconds until the billing period ends, and no charge. Raise the limit in the console to carry on.
Flood limits, per address
Before a key is read, each address may make at most the calls below, counted per hour. Past one, a call answers 429 with code rate-limited and a Retry-After, and carries no allowance headers, because no key was read. They are per address, so a busy integration sending everything from one address can reach them at the top of its plan. Spread the load across addresses, or ask support.
- /v1/
titles (batch), / v1/ recommendations, / v1/ changes6,000 an hour GET, HEAD
- /v1/
titles/ {titleRef}/ sources6,000 an hour GET, HEAD
- /v1/
search20,000 an hour GET, HEAD
- /v1/
discover, / v1/ lookup, / v1/ genres, / v1/ changelog60,000 an hour GET, HEAD
- /v1/
titles/ {titleRef} and its seasons, episodes, credits and images120,000 an hour GET, HEAD
- /v1/
people/ {personRef} and its filmography120,000 an hour GET, HEAD
- /v1/
account/ usage600 an hour GET, HEAD
- /v1/
account/ requests1,200 an hour GET, HEAD
- /v1/
account, / v1/ account/ keys3,000 an hour GET, HEAD
- /v1/
account/ keys/ {keyId}/ rotate40 an hour and 200 a day POST
- Any other /
v1 request120,000 an hour Any method
Every 429 the API records
Branch on code. metadata.errorCode names the exact cause, to log and to quote to support. Never branch on the message.
- 429quota-exhaustedPUBLIC_API_QUOTA_EXHAUSTED
your plan's daily or monthly request ceiling is reached; the refused call is not charged
- Content-Type
- application/json;charset=UTF-8
- RateLimit-Limit
- 1
- RateLimit-Remaining
- 0
- RateLimit-Reset
- 60
- Retry-After
- 60
- X-Calls-Remaining
- 0
- X-Quota-Grace
- false
- X-Quota-Reset
- 2026-10-01T00:00:00Z
- X-Request-ID
- 5f3c9a1e7b2d4c60
- X-Verifications-Remaining
- 10000
GET/v1/search
{ "timestamp": "2026-09-27T12:00:00Z", "status": 429, "error": "Too Many Requests", "message": "Your allowance for this period is spent. The limit reached was DAILY_REQUESTS.", "path": "/v1/search", "errors": [], "metadata": { "errorCode": "PUBLIC_API_QUOTA_EXHAUSTED" }, "code": "quota-exhausted" }429
- 429rate-limitedPUBLIC_API_DEMO_RATE_LIMITED
too many requests from your address before any key is read; with the public demo key, more than 10 calls a minute or 100 a day from your address, 500 a day from your network or 20 a second from everyone, a temporary block (1 minute, then 10 minutes, then an hour; a day without one starts again), or too many demo requests in flight at once
- Content-Type
- application/json;charset=UTF-8
- Retry-After
- 60
- X-Request-ID
- 5f3c9a1e7b2d4c60
GET/v1/search
{ "timestamp": "2026-09-27T12:00:00Z", "status": 429, "error": "Too Many Requests", "message": "The public demo key is at its limit for now. Try again in 60 seconds, or create a free API key for limits of your own.", "path": "/v1/search", "errors": [], "metadata": { "errorCode": "PUBLIC_API_DEMO_RATE_LIMITED" }, "code": "rate-limited" }429
- 429quota-exhaustedVERIFICATION_QUOTA_EXHAUSTED
your verification allowance for the day or the period is spent - checked before the reference is resolved
- Content-Type
- application/json
- RateLimit-Limit
- 1
- RateLimit-Remaining
- 0
- RateLimit-Reset
- 60
- Retry-After
- 60
- X-Calls-Remaining
- 9990
- X-Quota-Grace
- false
- X-Quota-Reset
- 2026-10-01T00:00:00Z
- X-Request-ID
- 5f3c9a1e7b2d4c60
- X-Verifications-Remaining
- 0
GET/v1/titles/{titleRef}/sources
{ "timestamp": "2026-09-27T12:00:00Z", "status": 429, "error": "Too Many Requests", "message": "Your allowance for this period is spent. The limit reached was DAILY_VERIFICATIONS.", "path": "/v1/titles/mv_EXAMP1E001/sources", "errors": [], "metadata": { "retryAfterSeconds": 60, "boundBy": "DAILY_VERIFICATIONS", "errorCode": "VERIFICATION_QUOTA_EXHAUSTED" }, "code": "quota-exhausted" }429
- 429rate-limitedPUBLIC_API_TOO_MANY_REQUESTS
too many requests from your address before any key is read
- Content-Type
- application/json;charset=UTF-8
- Retry-After
- 60
- X-Request-ID
- 5f3c9a1e7b2d4c60
GET/v1/titles/{titleRef}/sources
{ "timestamp": "2026-09-27T12:00:00Z", "status": 429, "error": "Too Many Requests", "message": "Too many requests from your IP address. Please try again later.", "path": "/v1/titles/mv_EXAMP1E001/sources", "errors": [], "code": "rate-limited", "metadata": { "errorCode": "PUBLIC_API_TOO_MANY_REQUESTS" } }429
Retrying
Wait what Retry-After says, then try again. With no Retry-After, back off exponentially with jitter. A spent allowance can ask you to wait until the period ends, so cap the wait and report it rather than sleeping for days.
# --retry retries a timeout, a 408, a 429 and a 500, 502, 503 or 504, waiting what Retry-After says (curl 7.66 or later).
# --fail-with-body (curl 7.76 or later) keeps the error body and exits non-zero on a 4xx or 5xx.
curl --fail-with-body --retry 4 --retry-max-time 120 \
-H "Authorization: Bearer $WAMBESHA_API_KEY" \
"https://api.wambesha.com/v1/search?q=gladiator"