# Rate limits and quotas

Plans are metered by two things: **request rate** (requests per second, with a burst allowance) and **monthly data transfer** (the bytes of the responses you receive). There are no request counts. Limits apply per organization: every key of an organization shares them.

## Plans:

The request rate and monthly data transfer of each plan are listed on the schedule of fees: [/pricing](https://www.secblast.com/pricing).

## Over the request rate

A request over the plan's request rate gets `429` with the problem code `rate_limited` and a `Retry-After` header in whole seconds. The body has `retry_after_ms`, the same wait to the thousandth of a second, and the plan's `limit_per_second` and `burst`. Wait that long, then send the request again.

## When the month's data transfer is used up

When the month's included data transfer is used up, requests stop with `429` and the problem code `quota_exceeded`, unless the organization holds prepaid credit. `Retry-After` is the time until the allowance resets. The body has `reason` (`allowance_used_no_credit`, or `credit_exhausted` when the credit ran out), `reset_at`, `included_bytes_remaining` and `credit_bytes_remaining`. Prepaid credit is part of the Business plan: it is bought up front and is drawn only for data transfer beyond the included amount, at the plan's per-GiB rate. Credit does not expire; it is forfeited, without refund, if you close your account. Nothing is billed after the fact. Allowances reset at the start of each calendar month, New York time (ET).

Responses with a `5xx` or `429` status do not count toward data transfer and do not draw credit.

## Headers

| Header | Value |
|---|---|
| `RateLimit` | How many requests the burst allowance has left now (`r`) and the seconds until it is full again (`t`), for example `"default";r=17;t=1`. |
| `RateLimit-Policy` | The plan's burst (`q`) and the seconds the plan's rate takes to refill it (`w`), for example `"default";q=20;w=1`. |
| `X-Quota-Limit-Bytes` | The month's included data transfer. |
| `X-Quota-Used-Bytes` | Data transfer used this month. |
| `X-Quota-Remaining-Bytes` | Included data transfer left this month. |
| `X-Quota-Reset` | When the allowance resets (RFC 3339). |
| `X-Credit-Remaining-Bytes` | What the organization's prepaid credit still buys, in bytes. |
| `Retry-After` | On a `429`: seconds to wait. |

An organization with unlimited data transfer gets `X-Quota-Used-Bytes` only. Browsers can read these headers on cross-origin requests.

## The proxy in front of the API

SEC Blast limits how fast one network address may send requests. A request over that limit is refused with a plain error page (status `429` or `503`), which is **not** a problem body and has no `code`. Pause, then retry.

## Using less data

- **Cache documents.** [`GET /v3/filings/{accession}/documents/{document}`](https://www.secblast.com/docs/reference/get-filings-accession-documents-document) sends an `ETag` (the SHA-256 of the stored bytes); send it back as `If-None-Match` and an unchanged document costs a `304` with no body.
- **Ask for part of a document** with a single-range `Range` header when you only need the start of a large file.
- **Filters run on the server**, so a narrowed list transfers only its matches.
- **A larger `limit`** means fewer requests for the same rows.
