Rate limits
On this page
Purpose
Billyou limits how often an organization can call the API. The limit is separate from the monthly document quota.
Default window
The default limit is 60 requests per minute per organization, counted in one sliding 60-second window. Every API key of that organization shares this window. There is no burst allowance.
Billyou can set a custom limit for an organization on request. X-RateLimit-Limit shows the limit that applies to the request you just made.
Partner routes
/api/partner/* and /api/plans/* use a separate threshold in that same organization window. The default is 600 requests per minute, or the provisioning limit Billyou has configured for that partner.
/api/partner/efactura/authorize and /api/partner/efactura/callback are also limited per client IP, at 60 requests per minute.
Response headers
Every response can include:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The limit that applies to this request |
X-RateLimit-Remaining | Requests left in the current window |
X-RateLimit-Reset | Unix time when the window resets |
Going over the limit returns HTTP 429 with errorCode RATE_LIMIT_EXCEEDED, a Retry-After header (seconds), and retryAfterSeconds in the body. See Errors.
Quotas
Rate limits and quotas are different counters. The API tracks apiRequests and apiEdocs. In the Developer Portal, an e-doc is any document created through the API (invoice, receipt, proforma, or anything else) and the counter is separate from the Billyou app's invoice quota.
The portal describes the number it shows as a monthly soft limit: a warning at 80 percent, and on paid plans a grace band of about 40 percent above the soft limit up to a hard cap. The same screen says paid API plans are not self-serve yet and that billing through Stripe for those plans is not switched on. Confirm the current plan state in the portal before you build upgrade flows. App subscriptions are a different system; see the Romanian Abonament și cont guide.