Personio returns 429 when a rate limit is exceeded, and the limits differ by endpoint rather than forming one global budget. Two details cause most real incidents. The authentication endpoint has its own limit of 150 requests per minute, and exceeding it drops you to one request per second for the next 60 seconds. And the Recruiting API's documents and applications endpoints are limited to 20 requests per 60 seconds per company, far tighter than anything else you are likely to call. An integration that re-authenticates before every call will hit the first one long before it hits the second.
The limits, in the order they will bite you
Scope
Approximate limit
Notes
Authentication endpoint
150 requests per minute
Then throttled to 1/second for the next 60 seconds
Recruiting API: documents, applications
20 requests per 60 seconds per company
Then wait 60 seconds
GET Employees
300 requests per minute, bursts up to 15 per second
Returns 429 above the limit
v1 endpoints overall
2,000 requests per minute per IP address
IP-based, across v1
Pacing yourself below these numbers is cheaper than recovering after a 429.
The mistake that causes most of these
Personio authenticates by posting credentials to an auth endpoint and receiving a bearer token. The naive implementation fetches a fresh token for each request, because that is the shape that most obviously always works.
In testing it does always work. In production it has two consequences:
It doubles your request count. Every operation becomes two calls.
Half of them hit the endpoint with the strictest limit and the worst penalty.
And the penalty is the part that hurts. Exceeding the auth limit does not just return 429 until the window resets. It drops you to roughly one request per second for the next 60 seconds. For a batch job that authenticates on every call, that turns minutes of work into a crawl without warning.
Fetch a token once, cache it for its lifetime, and refresh on a 401. That single change eliminates the most common cause of 429s against Personio.
Building around the recruiting documents limit
Twenty requests per sixty seconds is not a limit you handle with retries. It is a limit you design around.
At that rate, pulling a thousand documents takes fifty minutes at best, assuming nothing else competes for the same allowance. An integration that treats document export as an ordinary loop will either run for hours or fail partway through with most of the work lost.
What works instead:
Treat document export as a long-running background job, not a request-response operation.
Make it resumable, so an interruption continues rather than restarts.
Track which documents have already been fetched, so a rerun does not redo completed work.
Pace to the documents limit specifically, not to the limits of other endpoints.
Idempotency, because retries are inevitable
Rate limiting guarantees that some logical operations become multiple HTTP attempts. If those operations are writes, the absence of an idempotency strategy means retries can create duplicates: two absence records, two uploaded documents, two applicants.
This is worse than the rate limit itself. A throttled sync is slow; a duplicated absence record is wrong data in an HR system that someone has to find and remove.
What we do differently
Tokens are cached and refreshed on 401, never fetched per request. Most Personio rate-limit incidents disappear with this alone.
Pacing is per endpoint class. Documents get their own budget rather than sharing a global one, so a document export cannot starve an employee sync.
429 is treated as an expected operating condition, with exponential backoff and jitter, and it is measured rather than alarmed on. We alert when work misses its window.
Writes are queued and idempotent. A retry cannot create a second record.
Long jobs are resumable and report progress, so a document export that takes an hour is a visible job with a completion estimate rather than a process that either finishes or does not.
Frequently asked questions
Why would anyone re-authenticate on every call?
Because Personio uses a bearer token flow where you post credentials to get a token, and the simplest correct-looking implementation fetches a fresh token per request. It works in testing, where request volume is low. In production it doubles your request count and spends half of it on the endpoint with the strictest limit and the harshest penalty. Fetch a token once, cache it, and refresh on 401.
What is the auth endpoint penalty exactly?
Exceeding the authentication limit does not simply return 429 until the window resets. Further requests are accepted only at about one per second for the following 60 seconds, after which the normal allowance returns. That is a meaningful outage for a batch job: a sync that assumed it could authenticate freely goes from minutes to a crawl.
Why are recruiting documents so much tighter?
Personio limits the Recruiting API's documents and applications endpoints to 20 requests per 60 seconds per company, and after that you wait 60 seconds. Any integration that pulls documents in bulk has to be built around that number specifically. Pacing to the general limit and hoping is how a document export runs for hours and then fails near the end.
Are the limits the same across all Personio APIs?
No, and assuming so is a common source of surprise. Limits vary by API generation and by endpoint. Personio documents some limits per endpoint, for example 300 requests per minute with a burst of 15 per second on GET Employees and 2,000 requests per minute per IP address on the v1 endpoints, and not every endpoint has a published number. Treat 429 as the signal for the endpoint you are calling rather than applying one number everywhere.
What breaks if we just retry?
Duplicates, if the retried call was a write. Retrying an absence creation or a document upload without an idempotency strategy can produce two records where the user made one request. Rate limiting turns one logical write into several attempts, which is exactly when idempotency stops being optional.
Seeing this in production and want it to stop being your problem? We design, build, and permanently operate the pipeline, including the validation and retry logic that stops this class of failure reaching you. Fixed-price scoping quote within 48 hours.