Skip to the content

You are reading the reference as of 2026-10-04. The API serves the latest version. Read this page for the latest version

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

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.

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