Rate limiting

The OMS API uses a token-bucket rate limit based on query complexity. Every GraphQL response reports the current state in its extensions object:

{
  "data": { "...": "..." },
  "extensions": {
    "queryComplexity": 25,
    "bucketBalance": 9975,
    "bucketRestoreRate": 100
  }
}

• queryComplexity — the points the query you just ran cost. Richer and deeper queries (more fields, nested connections) cost more.
• bucketBalance — the points you have left, already net of the query you just ran.
• bucketRestoreRate — the points your bucket recovers every second.

How it works

Each query subtracts its queryComplexity from your bucketBalance. The bucket refills by bucketRestoreRate points every second, up to its maximum capacity.

For example, starting from a full bucket of 10000, a query costing 25 leaves you at 9975; with a restore rate of 100, one second later the bucket is full again (the refill never exceeds the maximum capacity).

When the bucket is not enough

A query that costs more than your current bucketBalance is rejected without executing and without consuming any points. The response is still HTTP 200, with a MAX_COMPLEXITY_EXCEEDED error and the usual extensions:

{
  "errors": [
    {
      "message": "Query 'heavy' has complexity of 16880, which exceeds bucket balance of 5848",
      "extensions": { "code": "MAX_COMPLEXITY_EXCEEDED" }
    }
  ],
  "extensions": {
    "queryComplexity": 16880,
    "bucketBalance": 5848,
    "bucketRestoreRate": 100
  }
}

In this case queryComplexity is the cost the rejected query would have had, and bucketBalance is left unchanged. To retry, wait for the bucket to refill: at least (queryComplexity - bucketBalance) / bucketRestoreRate seconds (about 111 seconds in the example above).

Note that a query whose complexity exceeds the bucket's maximum capacity can never succeed, no matter how long you wait: split it, request fewer fields, or use smaller pages instead of retrying.

Notes

• The exact figures (maximum capacity and restore rate) depend on your token's configuration — always read the real numbers from the extensions of each response instead of hard-coding them.
• To stay within budget, monitor bucketBalance and request only the fields you need: fewer fields and smaller pages mean a lower queryComplexity.