Rate limits

The e-bon API throttles incoming traffic to keep the service responsive for everyone. This page tells you which limits apply to your requests, how to read them from response headers, and how to retry safely when you hit one.

Understand the three buckets

Every request is counted against one or more independent buckets. The bucket with the lowest remaining capacity is what you hit first.

A few practical points:

• One API key shares one Global bucket and one Commands bucket. Two hundred terminals behind the same key share the same 50 commands per 10 minutes.
• The Auth bucket is keyed by IP only. Multiple users behind the same NAT or office Wi-Fi share that bucket — see Auth bucket and shared IPs below.
• The buckets do not chain. A POST /api/v1/commands call counts against both Global and Commands at once.

Read the rate-limit headers

Every response — not just 429s — carries the IETF draft-7 RateLimit headers:

A successful command submission with the Commands bucket nearly exhausted looks like this:

HTTP/1.1 201 Created
RateLimit-Limit: 50
RateLimit-Remaining: 3
RateLimit-Reset: 412
Content-Type: application/json

{ "id": "cmd_abc123", "status": "pending" }

The headers always reflect the bucket that produced the response. Read them, do not guess which bucket you are closest to.

Handle a 429 response

When a bucket is exhausted, the request never reaches the handler. You get back:

HTTP/1.1 429 Too Many Requests
Retry-After: 47
RateLimit-Limit: 150
RateLimit-Remaining: 0
RateLimit-Reset: 47
Content-Type: application/json

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests, please try again later.",
  "status": 429
}

The body is identical across all three buckets. Match on the top-level code === "RATE_LIMIT_EXCEEDED" to detect rate-limit responses.

Retry-After is always an integer number of seconds, with a minimum of 1. Wait at least that long before the next attempt — never retry a 429 immediately.

Back off correctly

A well-behaved client never relies on hitting 429 to discover it is going too fast. Bake the headers into your transport layer.

Code samples

These short reference clients show the header / Retry-After / jitter shape. They are not production-ready (no logging, no metrics, no circuit breaker) — adapt them to your stack.

async function callWithBackoff(url, options, attempt = 0) {
  const res = await fetch(url, options);
  if (res.status !== 429) return res;
  const retryAfter = parseInt(res.headers.get('retry-after') ?? '1', 10);
  const base = Math.max(retryAfter, 2 ** attempt);
  const jitter = base * (0.8 + Math.random() * 0.4); // ±20%
  if (attempt >= 5) throw new Error('rate limit: gave up after 5 retries');
  await new Promise((r) => setTimeout(r, jitter * 1000));
  return callWithBackoff(url, options, attempt + 1);
}

import random, time, requests

def call_with_backoff(method, url, attempt=0, **kwargs):
    r = requests.request(method, url, **kwargs)
    if r.status_code != 429:
        return r
    retry_after = int(r.headers.get('Retry-After', '1'))
    base = max(retry_after, 2 ** attempt)
    jitter = base * (0.8 + random.random() * 0.4)
    if attempt >= 5:
        r.raise_for_status()
    time.sleep(jitter)
    return call_with_backoff(method, url, attempt + 1, **kwargs)

attempt=0
while [ $attempt -lt 5 ]; do
  resp=$(curl -sS -D /tmp/h -o /tmp/b -w '%{http_code}' \
    -H "Authorization: Bearer $EBON_KEY" \
    -H 'Content-Type: application/json' \
    -X POST -d @body.json https://api.e-bon.ro/api/v1/commands)
  [ "$resp" != "429" ] && cat /tmp/b && break
  wait=$(awk 'tolower($1)=="retry-after:"{print $2+0}' /tmp/h)
  sleep "$((wait > 0 ? wait : 1))"
  attempt=$((attempt + 1))
done

Handle the Auth bucket on shared IPs

The Auth bucket is keyed by client IP, not by API key. The intent is anti credential-stuffing: a single IP cannot brute-force more than 30 login, register, or refresh attempts per 10 minutes regardless of how many usernames it cycles through.

The trade-off is that a corporate NAT, a shared office Wi-Fi, or a misconfigured reverse proxy can saturate the Auth bucket for everyone behind it.

If you operate a multi-tenant POS product where tenants share an outbound IP:

• Stagger refresh-token rotations so multiple tenants do not refresh in the same minute.
• Cache access tokens until ~60 seconds before expiry. Do not refresh on every request.
• If you genuinely need higher Auth throughput, run from distinct egress IPs.

Where to next

• API overview — the full request/response shape and authentication model.
• API errors — every error code you can receive, including RATE_LIMIT_EXCEEDED.
• Authentication — login, register, and refresh flows protected by the Auth bucket.
• Commands — the endpoint family protected by the Commands bucket.
• Idempotency — make safe retries with Idempotency-Key.