Rate limiting

The Tripletex API limits how fast an integration can call it. The limits keep the API fast and stable for everyone. A well-built integration rarely hits them.

This article covers the limits that apply to integrations, what a limited response looks like, and how to stay under the limits.

Heads-up: session token creation is now limited

An API key or employee token can create at most 180 session tokens per minute. We plan to lower this limit step by step, towards about 10 per minute. If your integration creates a new session token for every request, change it now to reuse the session token until it expires. See Session token creation.

The limits

Limit	What it counts	Current limit	When you go over
Request rate	All requests from one employee through one integration	100 requests per 10 seconds	429 for the rest of the 10 seconds
Changes on postings	GET /ledger/posting with changes in fields	300 requests per 5 minutes	429 for the rest of the 5 minutes
Failed requests	Failed requests in a row to one endpoint	30 failures in a row	429 on that endpoint, with a growing wait
Session token creation	Session tokens created with one API key or employee token	180 per minute, to be lowered	429 for the rest of the minute

The same limits apply in production and in the API test environment (api-test.tripletex.tech), so you can test how your integration handles them before you go live.

We can change the limits when needed. Do not hard-code them: read the headers described below.

Request rate

Each employee can make 100 requests per 10 seconds through one integration. The count is per employee and integration, so several API keys for the same employee in the same integration share one count.

Every response includes these headers:

Header	Meaning
X-Rate-Limit-Limit	The number of requests allowed in the current period
X-Rate-Limit-Remaining	The number of requests left in the current period
X-Rate-Limit-Reset	The number of seconds until the current period ends

When the limit is hit, every request gets 429 Too Many Requests until the period ends. The 429 response includes a Retry-After header with the number of seconds to wait.

Changes on postings

Requests to GET /ledger/posting that ask for changes in the fields parameter are expensive. They have their own limit of 300 requests per 5 minutes per employee and integration, on top of the request rate.

Failed requests

An integration that keeps sending a request that fails, for example in a retry loop, gets blocked on that endpoint.

• After 30 failed requests in a row to the same endpoint, that endpoint returns 429 for the employee.
• A failed request is any response with status 400 or higher, except 429.
• The count is per endpoint and HTTP method. Other endpoints are not affected.
• A successful request to the endpoint resets the count.
• If the requests still fail after the wait, the next wait is longer: 15, 30, 60, 75, 90 and then at most 120 seconds.

The blocked response has a Retry-After header and a JSON body in the usual error envelope:

{  "status": 429,  "code": 429,  "message": "Too many failed requests to this endpoint: 30 in a row. Fix the cause of the errors and retry after 15 seconds. A successful request resets the count.",  "requestId": "..."}

Retrying does not fix a 4xx error. Read the message and validationMessages in the error response, fix the request, and then send it again.

Session token creation

A session token is valid until its expiration date (or for the ttlSeconds you ask for). Create one, store it, and use it for all requests until it expires. You never need a new session token per request.

Applies to:

• PUT /token/session/:create
• POST /token/session/:create
• POST /token/session/:createFromRefreshToken

All three share one count per API key or employee token.

• Limit: 180 session tokens per minute. Over the limit you get 429 with Retry-After until the minute is over. The error body has code 26000 (RATE_LIMIT_EXCEPTION).
• Warning: once you create more than 10 session tokens in a minute, the response includes an X-Tlx-Session-Token-Warning header. If you see this header, your integration creates session tokens too often.
• Coming: we will lower the limit towards 10 per minute. Integrations that reuse their session token will not notice.

How to fix an integration that creates too many session tokens:

1. Create a session token and store it, together with its expiration.
2. Use the stored token for every request.
3. Create a new one only when the stored token is about to expire, or when a request gets 401 Unauthorized.
4. If several processes or servers call the API, share the stored token between them instead of letting each create its own.

Read more in Authentication and tokens.

Handling a 429

1. Stop sending requests to the limited endpoint.
2. Wait the number of seconds in Retry-After. If the header is missing, wait the number of seconds in X-Rate-Limit-Reset.
3. Retry once. If you get 429 again, wait longer before the next attempt (exponential backoff) and add some random delay, so that parallel workers do not retry at the same moment.
4. Never retry in a tight loop. A loop of failed requests makes the wait longer.

How to stay under the limits

• Reuse session tokens until they expire.
• Use webhooks instead of polling for changes. See Webhooks.
• Ask only for what you need. Use the fields parameter and search filters, and page through large results with from and count. See Integration best practices.
• Use checksums to skip fetching data that has not changed. See Checksum.
• Spread out heavy jobs. Throttle on the client side using X-Rate-Limit-Remaining, rather than sending as fast as possible and waiting for 429.
• Fix errors instead of retrying them. Log the requestId from failed responses. It helps us if you contact support.

Need help?

If you think the limits block a legitimate use case, contact us through Support. Include your integration name, the requestId of a limited response, and what the integration is doing.