Usage limits

Overview

ION applies fair-use guardrails to the /graphql endpoint so one caller’s heavy queries can’t degrade the API for everyone. To make guardrails discoverable rather than surprising, responses that touch a guardrail carry a limits block inside GraphQL extensions:

{
  "data": { "...": "..." },
  "extensions": {
    "limits": {
      "violations": [
        {
          "rule": "max_pagination_first",
          "field": "parts",
          "actual": "N",
          "limit": "N",
          "message": "Requested first: N on 'parts' exceeds the max page size of N."
        }
      ]
    }
  }
}

The block contains one field:

violations: a list of guardrails your request bumped against. Only present when non-empty. A clean request omits the block entirely.

Static caps (page size, depth, aliases, tokens, root fields) carry actual and limit numbers as shown. Rate-limit entries carry only the rule, retryAfter when applicable, and a message. The underlying rate budget is plan-dependent and intentionally not published in responses; follow the guidance in message rather than keying off a threshold.

When the block appears

The limits block is part of the response extensions, alongside anything else ION reports there. Treat it as optional and additive: parse it if present, ignore it if absent. Your existing data / errors handling does not change. A guardrail surfaces one of two ways, depending on where ION is in rolling a limit out to your org:

Phase	What you get	Request outcome
Advisory	The condition is reported under `extensions.limits.violations`	Request still succeeds: `data` is returned, no `errors`
Enforced	The condition is returned as a GraphQL error with a machine code	Request is rejected. See Error Codes

Advisory is your window to adapt a query before it starts getting rejected. Treat any violations entry as “fix this and you’ll be fine when enforcement turns on.”

A successful response with no violations carries no limits block at all. If you see extensions.limits, there’s something to address.

The `violations` array

Each entry is an object identified by its rule. Every entry carries a human-readable message; the other fields depend on the rule family.

Structural (query shape)

Static caps on the shape of the query document: page size, nesting depth, aliases, document size, and number of top-level fields.

{
  "rule": "max_pagination_first",
  "field": "parts",
  "actual": "N",
  "limit": "N",
  "message": "Requested first: N on 'parts' exceeds the max page size of N."
}

`rule`	Trips on	Fix
`max_pagination_first` / `max_pagination_last`	A `first` / `last` page size larger than allowed	Lower the page size and paginate with cursors
`max_depth`	Selection set nested deeper than allowed	Flatten the query; fetch nested data in follow-up requests
`max_aliases`	Too many aliased fields in one document	Split into multiple requests
`max_tokens`	Query document too large	Break the operation up
`max_root_fields`	Too many top-level fields in one operation	Split into multiple operations

actual and limit are always present on structural entries. field is included where a specific field is implicated (for example, pagination or depth) to point you at the offending part of the query.

Rate limit

A per-tenant token bucket meters sustained throughput. Because it’s a throughput signal, this entry carries the retry hint you need to back off:

{
  "rule": "rate_limit",
  "retryAfter": "seconds",
  "message": "Rate limit exceeded — retry after Ns."
}

Field	Meaning
`retryAfter`	Seconds to wait before the bucket has room again

Back off for retryAfter seconds, then resume. Spacing requests out helps you stay under the sustained rate.

A rate_limit entry without retryAfter is a permanent block: { "rule": "rate_limit", "message": "Access blocked. Contact support if you believe this is in error." }. Retrying doesn’t succeed until an operator lifts the block. Surface the message to the user and contact FirstResonance support, and don’t build a retry loop around it.

What enforcement looks like

When a guardrail is enforced rather than advisory, the same condition comes back as a GraphQL error carrying a machine-readable code, and the request is rejected. Key off errors[].extensions.code, not the message text:

`code`	Corresponds to
`QUERY_COMPLEXITY_EXCEEDED`	Any structural violation above
`RATE_LIMITED`	A transient `rate_limit` violation. Also returns HTTP 429 with a `Retry-After` header
`BLOCKED`	A permanent-block `rate_limit` violation (no `retryAfter`). Returns HTTP 200 with the GraphQL error rather than HTTP 429. Retrying doesn’t succeed, so contact support.

Full payload shapes and remediation live in Error Codes. The field vocabulary matches the advisory violations entries, so one parser can handle both paths.

Recommended client handling

For any integration, and especially unattended or agentic workflows that generate queries dynamically:

Check extensions.limits.violations on every response. No limits block means everything is clean; if the block is present, treat each entry as a to-do before enforcement flips on.
On a transient rate_limit (or HTTP 429), honor retryAfter with backoff and jitter. Don’t hot-loop.
On a rate_limit without retryAfter (or the BLOCKED error code), stop retrying. This is a permanent block that only lifts when an operator changes the configuration. Surface the message and contact support.
On structural violations, adapt the query. Use smaller pages, fewer fields, paginate, or split the operation. Retrying the same shape won’t help.
Don’t hard-code specific limit values. Structural actual and limit numbers are stable but plan-dependent; read them from the response so your client stays correct as plans evolve.

Error Codes: enforcement payloads (QUERY_COMPLEXITY_EXCEEDED, RATE_LIMITED, BLOCKED) and HTTP status reference.
Pagination: cursor paging to keep page sizes down.
Build a Production Integration: retry, backoff, and resilience patterns for unattended clients.

Getting Started

Build Hardware

Manage Supply Chain

Track Quality

Automate with ION

Administration

API Reference

Overview

When the block appears

The `violations` array

Structural (query shape)

Rate limit

What enforcement looks like

Recommended client handling

​Overview

​When the block appears

​The violations array

​Structural (query shape)

​Rate limit

​What enforcement looks like

​Recommended client handling

​Related

Overview

When the block appears

The `violations` array

Structural (query shape)

Rate limit

What enforcement looks like

Recommended client handling

Related