Skip to main content

Rate limits

An undocumented limit is indistinguishable from an outage, so here are the numbers.

SurfaceLimitCounted per
POST /oauth2/token20 per minutecredential, and separately per calling address
Everything under /v1600 per minutecredential

The /v1 limit is per credential, not per IP address. Two partners sharing a cloud egress address do not throttle each other, and running your integration from a dozen containers behind one NAT gateway does not count as one caller.

There is also a coarser per-address ceiling underneath, sized well above the per-credential limit so that a single partner spending its full 600 never reaches it. If you are seeing 429 while RateLimit-Remaining looks healthy, you are sharing an address with a lot of traffic — tell us and we will look.

Reading your budget​

Every /v1 response carries three headers:

RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 42
  • RateLimit-Limit — requests per minute for your credential.
  • RateLimit-Remaining — how many you have left right now.
  • RateLimit-Reset — seconds until your budget is back to full.

The bucket refills continuously rather than resetting on a fixed boundary, so you regain roughly ten requests a second as you go. You do not have to wait for Reset to hit zero before the next request succeeds — that value is the wait for the whole budget, not for the next single request.

note

Limits are enforced per API instance. Today we run a single instance, so the published numbers are the limits you get. If that changes, this page will say so. Either way, treat RateLimit-Remaining as a live signal to back off on, not as a ledger to plan against.

When you exceed it​

429 Too Many Requests, with a Retry-After in seconds and the same problem-details body as every other error:

HTTP/1.1 429 Too Many Requests
Retry-After: 3
RateLimit-Limit: 600
RateLimit-Remaining: 0
RateLimit-Reset: 58
Content-Type: application/problem+json
{
"type": "https://api.valueverde.de/errors/rate-limited",
"title": "Too Many Requests",
"status": 429,
"detail": "Rate limit exceeded for this API client. Retry after the period given in Retry-After, and see https://docs.valueverde.de/docs/rate-limits.",
"instance": "/v1/cooperatives",
"code": "RATE_LIMITED",
"trace_id": "9f2c1b7e-4d3a-4f18-93ac-2b6e5d0c8a71"
}

Sleep for Retry-After and try again. A refused request costs you nothing from the bucket, so retrying does not push your own recovery further away — but retrying without sleeping will not succeed any sooner either.

Quote trace_id if you contact support about a specific call.

Staying under it​

Cache your access token. This is the single most common cause of a 429 on the token endpoint. A token is valid for 15 minutes; mint one, hold it, and re-mint when it expires. An integration that fetches a token before every call will exhaust twenty a minute almost immediately — and it is doing an RSA signature per call for no reason.

Use conditional requests on the catalogue. GET /v1/cooperatives and GET /v1/cooperatives/{id} return ETag, and a 304 Not Modified still costs a request but nothing else. See Pagination & caching.

Back off on the header, not on the failure. If you are checking RateLimit-Remaining and slowing down as it approaches zero, you will rarely see a 429 at all.

Ask before you engineer around it. If a bulk reconciliation genuinely needs more than 600 a minute, that is a reasonable thing to want — email partners@valueverde.de rather than sharding across credentials, which we would read as abuse.

Other surfaces​

The public unauthenticated catalogue (/public/**) and the browser authentication endpoints have their own, tighter, per-address limits. Neither is part of the partner contract; if you are calling them from an integration, you are on the wrong endpoint.