OneOS Docs
Genesis 0.1.12 Console

Concepts

Rate limits

The gateway counts requests per principal (each API key, session or M2M client, in its organization) over one-minute windows. Past the limit it answers 429 RATE_LIMITED with a Retry-After header in seconds.

A limited request

HTTP/2 429
retry-after: 17
content-type: application/json
x-request-id: 2b4c…

{
  "error": {
    "type": "rate_limited",
    "code": "RATE_LIMITED",
    "message": "Too many requests for this principal; retry after Retry-After seconds.",
    "request_id": "2b4c…",
    "docs_url": "https://os.one.ml/api/v1/errors#RATE_LIMITED"
  }
}

Backing off

  • Wait the Retry-After seconds, then retry. Don't retry sooner: the window has not reset.
  • Spread bursts: separate keys per workload also give each workload its own budget.
  • Retry writes only with an idempotency key where the operation takes one, so a retry never acts twice.
async function withRetry(fn, attempts = 5) {
  for (let i = 0; ; i++) {
    try { return await fn() } catch (e) {
      if (e?.status !== 429 || i === attempts - 1) throw e
      await new Promise((r) => setTimeout(r, 1000 * 2 ** i))
    }
  }
}

Service limits

Some services keep their own limits on specific operations and answer 429 themselves, with their own body. Treat any 429 the same way.

One Superintelligence, Inc. · Built from Genesis 0.1.12 and the live gateway on 2026-10-20. Support