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. 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 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 depends on that account's role and plan, and administrator accounts are
exempt today. A 402 has two kinds of cause: the balance does not cover the lookups of the call
(out_of_credits), or the free trial of the account has ended and the account is read-only (trial_ended, see
A read-only account). Write your client to handle both as described in
Errors rather than to assume a balance.
Where credits apply:
POST /api/classify, a rerun, classifying one SKU and starting a batch can answer402with the codeout_of_creditswhen the balance does not cover the lookups the call would create. Thedetailnames the balance and what the call needs. These are the only operations that answerout_of_credits.- A lookup is charged to the account that owns it when it finishes. A lookup that ends with the status
erroris not charged. POST /api/skus/bulkwithclassify_missingnever answersout_of_credits: it answers200withclassification_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. On a read-only account the whole call is refused withtrial_endedbefore anything is saved.- 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). The figures in the example answers are illustrative.
An account on a free trial becomes read-only when the trial ends. The trial applies only to an account created on
or after 6 October 2026 (UTC), and only while the service has it switched on; for any other account trial in
GET /api/plans/me is null and nothing here applies. Once the trial has ended:
- Reading still works: lookups, batches, the catalog, the usage and the plan of the account, and exports of results that exist.
- A new lookup and every operation that changes something answer
402with the codetrial_ended. The balance does not matter: more credits do not lift it. Do not retry the call. - A key acts as the account that created it, so its trial is that account's. Only an administrator creates a key
and an administrator account is not on a trial, so a key does not normally receive
trial_ended. - In a batch that is running when the trial of its owner ends, the rows that were not processed yet end with the
status
errorand a message that says why (Batches).
What was left of the credits an account was given at sign-up is taken off after the trial ended, as a ledger row of the kind
trial_lapse (Usage). GET /api/plans/me says in advance whether an account is
read-only. The body of the refusal, and the operations that can answer it, are in
Errors.
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). 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, and trial and read_only, which say
whether the account is read-only (Usage). Plans are described on
https://htspilot.com/.
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 |
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. The values of this limit are not part of GET /api/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) |
| 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) returns the ones in force, with the defaults listed there. A request over the
upload size limit is answered 413 or 422 (Batches). The text of all
the cells of a file is held to the same size, counted in bytes
(Batches), and the column names of a file have a limit that follows
from it and from the rows of the file (Batches); a file over either is answered
422.