> ## 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.

> This page describes the API as of 2026-10-04. The service runs the latest version: https://docs.htspilot.com/rate-limits.md

# Rate limits and quotas

> What limits the use of the HTS Pilot API - credits, the limits of a plan, the few per-minute limits, the uploads read at once, 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, the number of uploaded files read at once, and the size of a request.

Send requests at a pace your integration needs, and keep to the polling guidance in
[Asynchronous work](/v/2026-10-04/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](/v/2026-10-04/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](/v/2026-10-04/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](/v/2026-10-04/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` |

## Uploads read at once

This is not a limit per minute and does not count your calls. The service reads a limited number of uploaded files
at the same time (2 unless the service is configured otherwise), because a file is read whole into memory. An
upload (`POST /api/batches`) that finds no room waits in line, first come first served, for up to 30 seconds
(unless the service is configured otherwise, and never more than 90). Then it is answered `429` with the code
`rate_limited`, the header `Retry-After: 10` and `details.retry_after_seconds: 10`. When the line is already full,
the same answer comes at once.

A second bound applies before the file is read: the service takes at most 16 upload bodies at the same time (unless
it is configured otherwise), three of them from one caller. A body counts from the moment the service lets it
through until its last byte has arrived. One more is answered `429` at once with the same body, `Retry-After: 10` and
`details.retry_after_seconds: 10`, and nothing of its body is kept.

The places are shared between callers. A caller is an API key: two keys of one account are two callers. One caller
holds one place at a time and may have two more uploads waiting; one upload more from the same caller is answered
`429` at once, with the same body, `Retry-After: 10` and `details.retry_after_seconds: 10`. Send the uploads of one
key one after the other. A place is held until the answer of the upload has been read, which the service allows 10 to
60 seconds for (the time the size of the answer takes at 64 KiB per second, counted from the start of the answer;
the answer of an upload is small, so about 10 seconds), and not only until the file is parsed.

The file was not read and no batch was created, so the same upload can be sent again after the wait. Give an
upload a request timeout above 90 seconds plus the time your connection needs to send the file. The whole case, with what to do after other failures of an upload, is
in [Batches](/v/2026-10-04/batches.md#an-upload-that-waits-429). The values of this limit are not part of `GET /api/limits`.

## 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](/v/2026-10-04/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) |

The limits of the service on a batch file are not fixed numbers: `GET /api/limits`
([System](/v/2026-10-04/system.md#request-limits)) returns the ones in force, with the defaults listed there. A request over the
upload size limit is answered `413` or `422` ([Batches](/v/2026-10-04/batches.md#a-file-that-is-too-large-413)). The text of all
the cells of a file is held to the same size, counted in bytes
([Batches](/v/2026-10-04/batches.md#how-the-text-of-a-file-is-counted)), and the column names of a file have a limit that follows
from it and from the rows of the file ([Batches](/v/2026-10-04/batches.md#the-column-names)); a file over either is answered
`422`.
