Rate Limits
Luqra Now limits how fast an organization may call the /v1 endpoints. The limit is a sliding window, applied twice:
- Per second -- a maximum number of requests in any trailing 1 second.
- Per minute -- a maximum number of requests in any trailing 60 seconds.
A request is served only when every configured window has room. An unset window is not limited. The limits are the same for every organization, but each organization is counted on its own: another organization's traffic never uses up yours. All API keys of one organization share its windows, so two integrations on two keys draw from the same limits.
Luqra announces the limits before enforcing them, and they can change. The response headers below always carry the values that apply to you.
How the window works
There is no fixed reset point. Each request stays in a window for as long as the window is long, then leaves it and frees one slot. A request refused with 429 is not counted, so retrying a refused request never extends the wait.
Only authenticated requests are counted. A request rejected with 401 or 403, or answered with 503 because the key lookup was unavailable, counts against neither window. Every authenticated request counts, including one that the API then rejects with a 400.
Rate limit headers
Every response to an authenticated /v1 request carries these headers for each configured window, unless the limit could not be checked (see When the headers are absent):
| Header | Description |
|---|---|
X-RateLimit-Limit-Second | Requests your organization may make in any trailing second |
X-RateLimit-Remaining-Second | Requests the per-second window still admits after this one. 0 when this window is full |
X-RateLimit-Limit-Minute | Requests your organization may make in any trailing minute |
X-RateLimit-Remaining-Minute | Requests the per-minute window still admits after this one. 0 when this window is full |
curl -i "https://staging.api.now.luqra.com/v1/originators?limit=1" \
-H "Authorization: Bearer luqra-now.org.test.YOUR_API_KEY"
HTTP/1.1 200 OK
X-RateLimit-Limit-Second: 10
X-RateLimit-Remaining-Second: 9
X-RateLimit-Limit-Minute: 300
X-RateLimit-Remaining-Minute: 299
The numbers on this page are illustrative. Read the real limits from your responses.
When the limit is reached
The API answers 429 Too Many Requests with the RATE_LIMITED code and does not process the request:
HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit-Second: 10
X-RateLimit-Remaining-Second: 0
X-RateLimit-Limit-Minute: 300
X-RateLimit-Remaining-Minute: 142
{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Retry after the number of seconds in the Retry-After header.",
"correlationId": "5f0c6a2e-8d1b-4c7a-9e3f-2b6d4a1c8e70"
}
}
| Header | Description |
|---|---|
Retry-After | Whole seconds, at least 1, until every window that was full has room again |
correlationId identifies the request in Luqra's logs. Include it when you contact support.
Handling limits
- Watch the
Remainingheaders and spread requests out as they approach0, rather than waiting for a429. - On
429, waitRetry-Afterseconds, then retry the same request. Add some random jitter so that several clients do not retry at the same instant. Retrying sooner is refused again. - Retry
POST /v1/paymentswith the sameIdempotency-Key. The rate limit answers before the payment is created, so a refused request does not reserve the key. See Idempotency and Retries. - Remember that all of your organization's keys share the windows. A burst from one integration reduces what another can send.
- Prefer larger pages to many small requests on list endpoints, within the
limitthe endpoint allows.
What is not limited
- Requests that fail authentication (
401,403) and the key lookup503. - Public documentation routes that need no API key.
Monitoring mode
Luqra can run the limit in monitoring mode. The API then counts requests and sends the X-RateLimit-* headers (never Retry-After), but serves requests past the limit instead of answering 429. A successful response can then carry Remaining of 0. Treat that as a signal to slow down: the same traffic is refused once the limit is enforced.
When the headers are absent
- No headers -- no limit is configured, or Luqra could not check the limit for a moment.
- Only the
Secondor only theMinuteheaders -- only that window is configured. The other window is not limited.
The limiter is built never to refuse a request because of its own failure. When it cannot check, the request is served and the headers are left out.
See Errors for the full error reference.