> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate limits and quotas

> What limits the use of the HTS Pilot API - credits, the limits of a plan, the few per-minute limits, and the size limits of a request.

The API has no general limit of requests per minute, per key or per plan, and returns no rate limit headers
(no `X-RateLimit-*`). What limits use is listed here: credits, the plan of the account, a few limits on specific
operations, and the size of a request.

Send requests at a pace your integration needs, and keep to the polling guidance in
[Asynchronous work](/asynchronous-work.md). Work that is classified (lookups, batch rows) is queued and processed
in the background, so sending more at once does not make it finish sooner.

## Credits

Credits are counted against the account that owns the work: for a call made with an API key, the account that
created the key. Whether a call is charged, and whether it can be refused with `402`, depends on that account's
role and plan, and administrator accounts are exempt today. Write your client to handle `402` as described in
[Errors](/errors.md#handling-errors) rather than to assume a balance.

Where credits apply:

- `POST /api/classify`, a rerun, classifying one SKU and starting a batch can answer `402` with the code
  `out_of_credits` when the balance does not cover the lookups the call would create. The `detail` names the
  balance and what the call needs.
- A lookup is charged to the account that owns it when it finishes. A lookup that ends with the status `error`
  is not charged.
- `POST /api/skus/bulk` with `classify_missing` never answers `402`: it answers `200` with
  `classification_queued`, and the lookups are created afterwards, in the background. A lookup that cannot be
  charged is not created, and the SKU stays without a suggested code. Read the SKUs to see which were classified.
- A batch that runs out of balance while it runs marks the remaining rows as failed with the reason.

`GET /api/usage/me` returns the balance (`credits`) and whether the account is exempt (`unlimited`)
([Usage](/usage.md)). The figures in the example answers are illustrative.

## Plan limits

The plan of the account that created the key decides which features are on and how large some things may be. An
account without a plan is not restricted. A refusal is a `403` with the code `plan_feature` or
`plan_limit` ([Errors](/errors.md#plan-refusals)). The limits enforced on API calls today:

| Entitlement | What it gates |
| --- | --- |
| `feature.batch` | Uploading, starting, retrying and editing a batch, and classifying the SKUs of a bulk sync. Finished batches stay readable and exportable |
| `batch_max_rows` | The number of rows of a batch file, checked at upload and again at start, and the number of SKUs a bulk sync classifies |
| `feature.webhooks` | Creating, changing and testing a webhook |
| `feature.reports` | The productivity report |

`GET /api/plans/me` returns every entitlement of the plan with its value. Plans are described on
<https://htspilot.com/>.

## Limits per minute

Three limits apply to specific operations:

| What | Limit | Answer |
| --- | --- | --- |
| Comments on lookups (`action: "comment"` of a decision) | 20 per minute per account, across all lookups | `429` with `Retry-After: 60` |
| Comments on one lookup | 500 in all | `409` |
| Test events of a webhook (`POST /api/webhooks/{hook_id}/test`) | 5 per minute per webhook, 20 per minute per administrator | `429` with `details.retry_after_seconds: 60` |

## Size limits

| What | Limit |
| --- | --- |
| `description` of a lookup or a SKU | 2000 characters |
| `material`, `use`, `composition` | 500 characters each |
| `notes` | 1000 characters |
| Items in one `POST /api/skus/bulk` | 5000 |
| `page_size` of a list | 200, or 500 for SKUs ([Pagination](/pagination.md)) |
| A batch file | Limited in megabytes and in rows by the service, and in rows by the plan (`batch_max_rows`, checked at upload and at start) |