API documentation

Rate Limits

The Demarky API admits requests through an IP gate before authentication, then atomically charges application, installation, and token buckets. Installation access also charges the paying account's own bucket. Limits vary by operation and are communicated on every response; clients should use the response headers instead of hard-coding quotas.

Headers

Every response includes rate limit headers:

Header	Description
`RateLimit-Limit`	Most constraining limit for the current request window
`RateLimit-Remaining`	Remaining requests in the current window
`RateLimit-Reset`	Unix timestamp when the most constraining window resets
`RateLimit-Policy`	Most constraining dimension and window, such as `app;w=60`
`Retry-After`	Seconds until the next retry (only on 429 responses)

Handling rate limits

When a rate limit is exceeded, the API returns 429 Too Many Requests:

{
  "error": "rate_limit_exceeded",
  "message": "Application rate limit exceeded",
  "request_id": "cce50960-a535-4472-a7a7-5b4f9719aa42",
  "details": {
    "dimension": "application",
    "retry_after_seconds": 43
  }
}

Use the Retry-After header or the retry_after_seconds value to determine when to retry. The dimension identifies only the caller's limiting bucket and never exposes another tenant's usage.