API rate limits
Each thirds.ai API key can send 5 render requests per second, with a burst of 21 after a quiet spell. Each key can have 8 live jobs at once, and each account can have 16. Every plan has these same limits. A paid plan gives you more credits and an earlier place in the queue, and it doesn't raise the limits. When you go over a limit, the API answers with a 429 response and a Retry-After header that tells you how many seconds to wait.
Give this prompt to your AI agent. The agent does the task for you.
Read https://thirds.ai/docs/rate-limits and help me set request concurrency and safe retries for thirds.ai using its rate, size, and queue limits.
With thirds.ai, you save a design once, such as an invoice, a report, a certificate, or a social post. Then your app sends new details for every order or every row and gets a finished PDF or image back with your logo, colours, and fonts, with no design work each time. A verified account gets 50 free credits each month to try it. The PDF generation API guide shows how to send your first request. You don't need code to make a file. To make one in the editor, read how to make a template you can reuse.
Why does the thirds.ai API have rate limits?
We set rate limits so that one busy app can't slow down everyone else's files, and so that every PDF and image stays inside safe size and time limits. The limits are the same on every plan, from Free to Scale. They're safety controls, so they don't promise a set number of files per minute. There's no lifetime cap on how many files you make.
If your app needs more files sooner, send them at a steady rate and let them wait in the queue. A paid plan moves your work up the queue. For credit grants and spend limits, read credits and billing.
Request and job limits
Each thirds.ai API key can send 5 render requests per second and keep 8 live jobs, and one account can keep 16 live jobs across all its keys. A live job is one that is queued or running. PDF and image work share the same account slots. So a safe setup for one key is a pool of 8 or fewer workers that each wait for their job to end before they send the next one.
| Limit | Maximum |
|---|---|
| API-key submission rate | 5 per second, with an idle burst of 21 |
| Live jobs per API key | 8 |
| Live jobs per account | 16 |
| Paid queued-job backlog | 100,000 across the service |
| Anonymous playground allowance | 200 renders per browser per month |
The burst of 21 lets a quiet key send a short rush of requests. It doesn't add live-job slots. The playground also has CAPTCHA, address rate controls, and its own live-job cap.
Render size limits
One thirds.ai render can take a request body of up to 8 MiB. It can make a PDF of up to 100 pages or an image of up to 32,000,000 pixels, and either file can be up to 25 MiB. These size limits keep one large file from holding a worker for too long. A render that goes over a limit fails and spends no credits.
| Limit | Maximum |
|---|---|
| Render request body | 8 MiB |
| HTML input | 5 MiB |
| Template source | 1 MiB |
| Template data | 3 MiB of canonical JSON |
| Template data depth | 32 levels |
| One data collection | 10,000 items |
| Total template data values | 50,000 |
| One fetched asset | 10 MiB |
| All fetched assets | 20 MiB across at most 128 assets |
| PDF output | 100 pages and 25 MiB |
| Static-image output | 32,000,000 pixels and 25 MiB |
| Image width | 320 to 7680 pixels |
| Image height | 200 to 4320 pixels |
| Worker render time | 30 seconds |
| JavaScript ready-marker wait | 2 seconds |
Memory, CPU, browser processes, temporary storage, and template evaluation also have fixed safety limits. Repeated failed renders can still trigger abuse limits, even though each failure is free. If you hit a size limit, split large documents, resize images, and remove unused assets before you try again. For page sizes and image formats, read PDF and image options.
How do I fix a 429 rate limit error?
To fix a 429 error from the thirds.ai API, wait for the number of seconds in the Retry-After header, then send the same request again. HTTP 429 means Too Many Requests, so it is the rate-limit response. The fix takes three steps, and you need the response and the Idempotency-Key you sent the first time.
- Read
Retry-Afterin seconds. The same value is aterror.retry.retry_after_secondsin the response body. - Wait at least that long. When many workers retry together, add a small random delay to each one.
- Send the render request again with the same
Idempotency-Keyand the same input. If a job for that key already exists, you get that same job back, so you never pay twice.
The error.code tells you which limit you hit:
| Response | What to do |
|---|---|
429 rate_limited | Slow down. The current retry delay is between 1 and 60 seconds. |
429 account_concurrency_limited | Wait for your account's active jobs to finish. The response gives a 5-second retry delay. |
429 key_concurrency_limited | Wait for this key's active jobs to finish. The response gives a 5-second retry delay. |
429 abuse_limited | Fix repeated failures. The response gives a 3600-second retry delay. The daily failure count can still block a later attempt. |
503 overloaded | Wait for the 30-second retry delay before submitting again. |
202 with a job | Poll the route in Location. Retry-After: 1 gives the initial polling delay. |
The API doesn't send a remaining-request counter or X-RateLimit-* headers. Use Retry-After, the response code, and your own count of active jobs. A retry header tells you when to try next. It can't promise that a slot is free at that time.
Give each client a deadline and a retry limit. If the deadline ends while a job is active, save its ID and read it later. Don't create a new job just because your request timed out. For the full retry and download steps, read retry requests and download files.
Understand queue order
The thirds.ai queue sorts jobs by the time they arrive plus a priority offset for your plan. The offsets are 0 seconds for Scale, 30 seconds for Growth, 2 minutes for Starter, 5 minutes for packs, 10 minutes for Free, and 15 minutes for anonymous work.
The offsets only sort jobs. They don't set a fixed wait or promise a finish time. Older work gains priority, so jobs on every plan still run. Keep polling the same job while it is queued. Webhooks can tell your server when the job ends.
For a specific refusal or failed job, read the error guide.