Skip to the content

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

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 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. These are the only operations that answer out_of_credits.
  • Starting, or retrying, a batch of another account, which a key with the reviewer or admin role can do, can answer out_of_credits too. Its detail then says only that the credits that pay for the batch do not cover its rows and that the owner of the batch is the one to ask: it carries no balance and no amount, because those belong to the account that owns the batch. The owner of the batch is answered with the balance and the amount.
  • 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 out_of_credits: 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. On a read-only account the whole call is refused with trial_ended before anything is saved.
  • A batch that runs out of balance while it runs marks the remaining rows as failed with the reason. For a reader who is not the owner of the batch, in the list of rows and in the exported file, that reason says that the credits that pay for the batch had run out, without the owner's figures.

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 402 with the code trial_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 error and 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.

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). 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/.

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

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 account: its API keys and its own sign-in sessions count together, so two keys of one account are one caller. One caller holds one place at a time and may have two more uploads waiting, and may have three bodies arriving at once; one upload more from the same caller is answered 429 at once, with Retry-After: 10 and details.retry_after_seconds: 10. In English its detail is "You already have 3 files being sent or waiting to be read. This file was not read; send it again in 10 seconds." Send the uploads of one account one after the other, whatever keys they use. 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.

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)
The body of a request that is not an upload 1 MiB (1,048,576 bytes). POST /api/skus/bulk takes a body as large as an upload file, max_upload_mb of GET /api/limits. A larger body is answered 413 with the code payload_too_large (The body of a request)
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.

Every request that is not an upload has a bound on its body: 1 MiB, or for POST /api/skus/bulk the size of an upload file (max_upload_mb of GET /api/limits, 25 MB at the default). A body that declares a larger Content-Length is answered 413 with the code payload_too_large before the body is read, and before the key is checked, so such a 413 does not tell you whether the key is valid. A body sent without a declared length is counted as it arrives and refused when the count passes the bound. In English the detail is "The request body is larger than 1 MB, the most this address accepts." with the bound in force. Nothing was processed, and the same body is refused again: do not retry it, send less. The limit on the items of one POST /api/skus/bulk call is in System.