Copy page

Documentation

Errors & limits

Error format

Errors raised by the API itself have one JSON shape:

Code
{"error": "missing or invalid API key"}

The one exception is parameter validation (422 for a missing, malformed or out-of-range parameter), which uses the framework format:

Code
{"detail": [{"type": "less_than_equal", "loc": ["query", "limit"],
             "msg": "Input should be less than or equal to 100",
             "input": "101", "ctx": {"le": 100}}]}

Status codes

Status	Body	When	What to do
200	the result	Success.	—
401	{"error": "missing or invalid API key"}	No X-API-Key header, or the key is unknown, revoked or replaced.	Check the header and the key.
402	{"error": "API key inactive: trial ended or payment due"}	The key is known but not active: its trial ended or a payment is due.	Contact us to (re)activate it.
404	{"error": "job not found"}	GET /v1/jobs/{job_id} with an id that does not exist.	Nothing — it costs nothing.
422	{"error": "invalid cursor"}	A cursor this API did not issue.	Restart without cursor.
422	{"error": "q must be at least 3 characters"}	Search term shorter than 3 characters after trimming.	Use a longer q.
422	{"detail": [ … ]}	A parameter is missing, has the wrong type or is out of range (e.g. limit=101, missing q, q over 200 characters, non-integer job_id).	Fix the parameter.
429	{"error": "rate limit exceeded"} + Retry-After header	Too many requests in the current minute.	Wait Retry-After seconds.
429	{"error": "monthly allowance used up"} (no Retry-After)	No jobs left in this month's allowance.	Wait for the 1st of next month (00:00 UTC) or upgrade your plan.
500	{"error": "internal"}	Unexpected server error.	Retry later; contact us if it repeats.
503	{"error": "service temporarily unavailable"}	A backing service is unavailable or a query took too long.	Retry with exponential backoff.

Only a 200 counts against your allowance. 401, 402, 404, 422, 429, 500 and 503 count nothing.

Order of checks

A request is checked in this order; the first failing check decides the answer:

1. Parameters (422)
2. API key (401, 402)
3. Per-minute rate limit (429 with Retry-After)
4. Monthly allowance (429 without Retry-After)
5. The query itself (404, 500, 503, or 200)

Rate limit

• 60 requests per minute per key.
• The window is the calendar minute in UTC (it resets at second :00), not a rolling 60 seconds.
• Every request that gets past the key check counts toward the minute — including requests that are themselves answered 429.
• Over the limit you get 429 {"error": "rate limit exceeded"} with a Retry-After header: the number of seconds (1–60) until the next minute starts.

Monthly allowance

• Your plan gives each key an allowance of jobs per month. See pricing for the allowance of each plan.
• What counts: each job returned in a 200 response counts once. A page of 20 jobs costs 20; an empty page costs 0; GET /v1/jobs/{job_id} costs 1 when found and 0 on 404. The number of jobs returned is charged, not the limit you asked for.
• Near the end of the allowance a page is cut to what is left: with 5 jobs left, limit=20 returns 5 jobs, and has_more is true if more jobs follow.
• When it is used up, every /v1 request answers 429 {"error": "monthly allowance used up"} — including GET /v1/jobs/{job_id} — until the allowance resets.
• Parallel requests: while a request is running, the jobs it may return are held for it, and a request that ends up returning fewer gives the rest back when it finishes. So with requests in flight at the same time, a page can be cut short, or a request can get the allowance 429, even though jobs come free a moment later. If X-Jobs-Remaining on your last 200 was above 0, wait for your other requests to finish and retry before treating the month as used up.
• Reset: months are calendar months in UTC. The allowance resets on the 1st of each month at 00:00 UTC. Unused jobs do not carry over.

Response headers

Header	On	Meaning
X-Jobs-Remaining	200 responses, keys issued by us	Jobs left in your monthly allowance after this response. Not sent on requests made through RapidAPI — RapidAPI tracks that usage.
Retry-After	rate-limit 429	Seconds to wait before the next request (1–60).
Cache-Control: no-store	every /v1 response	Responses are not cached by browsers or proxies.

Use X-Jobs-Remaining to track usage: read it after each request and slow down or stop before it reaches 0.