Skip to main content

TokenQuota

A named per-token quota pool with matchers that classify outgoing requests into the pool.

  • type: object
  • required: ["type","name","remaining_path","reset_path"]

type​

  • Required: Yes
  • type: string
  • enum: ["TokenQuota"]

name​

Name of the quota pool.

  • Required: Yes
  • type: string

Examples:

rest
graphql

remaining_path​

Path to the remaining call count for this pool in the quota status response.

  • Required: Yes
  • type: array

Examples:

- resources
- core
- remaining

  • items:

    • type: string

reset_path​

Path to the quota reset timestamp for this pool in the quota status response.

  • Required: Yes
  • type: array

Examples:

- resources
- core
- reset

  • items:

    • type: string

limit_path​

Optional path to the total call limit for this pool in the quota status response. Used to compute the proactive throttling reserve; falls back to the initially observed remaining count when not set. Setting it on every pool is recommended so the reserve does not shrink when a sync starts with the pool already partially consumed.

  • Required: No
  • type: array

Examples:

- resources
- core
- limit

  • items:

    • type: string

matchers​

List of matchers that classify outgoing requests into this quota pool. The first pool whose matcher matches a request is used. A pool with no matchers acts as the default pool.

remaining_header​

Optional response header carrying the remaining call count for this pool. When set, the pool's counter is reconciled against this header on every response, which corrects drift caused by sharing the token with other clients, by requests in flight concurrently, or by a sync running long enough for the initial quota status read to go stale. Without it the pool is only ever seeded from the quota status endpoint.

  • Required: No
  • type: string

Examples:

X-RateLimit-Remaining

reset_header​

Optional response header carrying the quota reset timestamp for this pool. Parsed with the same rules as reset_path, so epoch seconds and ISO 8601 both work. Used to tell a rolled-over quota window from the current one; a response proving the window has rolled over restores the pool to its limit. Most useful alongside remaining_header.

  • Required: No
  • type: string

Examples:

X-RateLimit-Reset

limit_header​

Optional response header carrying the total call limit for this pool, used to keep the proactive throttling reserve accurate as the limit changes.

  • Required: No
  • type: string

Examples:

X-RateLimit-Limit

exhaustion_status_codes​

Response status codes that mean this token's pool is spent. These have two effects. A response carrying one of them but no remaining count sets the pool to zero, so the next request rotates to another token instead of waiting out the reset window. They also mark which responses may report a zero for a quota window that has already elapsed, so a rate limit whose reset header trails the value being held still stops the token being used; a zero on any other response is treated as the last call of a finished window and ignored. Leaving this empty means such trailing rejections are ignored unless their reset is within the skew tolerance of the current window. Only list codes the API uses exclusively for rate limiting -- a code that also signals other failures would park a healthy token.

  • Required: No
  • type: array

Examples:

- 429

  • items:

    • type: integer

$parameters​

  • Required: No
  • type: object
Was this page helpful?