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

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)