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):

HeaderDescription
X-RateLimit-Limit-SecondRequests your organization may make in any trailing second
X-RateLimit-Remaining-SecondRequests the per-second window still admits after this one. 0 when this window is full
X-RateLimit-Limit-MinuteRequests your organization may make in any trailing minute
X-RateLimit-Remaining-MinuteRequests 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"
  }
}
HeaderDescription
Retry-AfterWhole 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 Remaining headers and spread requests out as they approach 0, rather than waiting for a 429.
  • On 429, wait Retry-After seconds, 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/payments with the same Idempotency-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 limit the endpoint allows.

What is not limited

  • Requests that fail authentication (401, 403) and the key lookup 503.
  • 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 Second or only the Minute headers -- 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.