> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/getting-started/rate-limiting.md).

# Rate Limiting

API requests are subject to two types of rate limiting:

#### Per-Minute Rate Limit

* **100 requests per 60-second window** (fixed window)
* Applies to account API key requests only. Approved third-party developer applications are metered separately and are subject to neither the per-minute limit nor the monthly quota.
* Response headers on every request:
  * `X-RateLimit-Limit`: Maximum requests allowed (100)
  * `X-RateLimit-Remaining`: Requests remaining in current window
  * `X-RateLimit-Reset`: Unix timestamp when the window resets

#### Monthly Request Quota

Monthly limits are based on your Spiffy subscription plan:

| Plan     | Monthly Limit |
| -------- | ------------- |
| Pro      | 10,000        |
| Business | 20,000        |
| Scale    | 50,000        |

* Response headers on every request:
  * `X-Monthly-RateLimit-Limit`: Your quota for the current month
  * `X-Monthly-RateLimit-Remaining`: Requests remaining this month
  * `X-Monthly-RateLimit-Reset`: Unix timestamp for the first of next month (UTC)
* An email warning is sent when usage reaches 80% of the monthly limit.
* Your quota can change during a month — Spiffy support can grant a temporary increase, which ends at the reset. `X-Monthly-RateLimit-Limit` always reflects the quota currently in force, so read it per response rather than caching the table above.

When either limit is exceeded, the API returns **429 Too Many Requests**. The two limits return different error codes, and they need different handling — branch on `error.code` rather than on the status alone.

Per-minute limit exceeded. Retryable; a `Retry-After` header gives the number of seconds to wait:

```json
{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests"
  }
}
```

Monthly quota exhausted. **Not retryable** — there is no `Retry-After` header, and requests will continue to fail until the quota resets at the start of the next month (see `X-Monthly-RateLimit-Reset`). Retrying will not succeed, and each rejected attempt is itself counted, so a retry loop consumes the quota it is waiting on:

```json
{
  "error": {
    "code": "monthly_limit_exceeded",
    "message": "Monthly API request limit exceeded"
  }
}
```
