Skip to the content

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

Errors

The error body of the HTS Pilot API with its machine-readable code, the status codes in use, validation errors, plan refusals and how messages follow Accept-Language.

An error is answered with an HTTP status of 4xx or 5xx and a JSON body. It is never a 200 with an error inside.

The error body

{ "detail": "Lookup not found", "code": "not_found" }
Field Type Meaning
detail string What went wrong, written for a person, in the language of the request
code string What went wrong, for a program. In every error the API writes
request_id string Only on a 500: the value of the X-Request-ID header of the answer
details object More about the error, when there is more to say. Absent otherwise
errors array Only on a 422 for invalid input: one entry per invalid field, see below

Branch on code and show detail. code is lower snake case, the same in every language, and is not changed once it is published. detail is a sentence: it is translated (Languages) and its wording can change. Every answer also carries the header X-Request-ID (Request identifiers).

Error codes

Most errors carry the code of their status. A few are more specific:

code Status Meaning
bad_request 400 The request cannot be carried out as it was sent
unauthenticated 401 No valid API key was sent, or it was not accepted
payment_required 402 The call needs something the account has not paid for
out_of_credits 402 The credits of the account are used up
trial_ended 402 The free trial of the account has ended and the account is read-only. details.trial_ended_at says when (A read-only account)
owner_trial_ended 402 The call would start work on a batch that belongs to another account, and the free trial of that account has ended. The answer does not say when
forbidden 403 The call is refused for this caller, usually because of its role
plan_feature 403 The plan of the account does not include this function. details.key names it
plan_limit 403 The call goes over a limit of the plan. details has the limit and what was asked
session_required 403 The call needs a person signed in to the application; an API key cannot make it (Workspace refusals)
workspace_mismatch 403 The request names another workspace than the one its API key belongs to
member_suspended 403 The membership in the workspace is suspended
workspace_required 403 The caller acts in no workspace, so it has none to work in
workspace_not_found 404 The workspace named by the request does not exist, or the caller is not a member of it
not_found 404 The address or the record does not exist, or belongs to another user
method_not_allowed 405 The address exists and does not take this method
request_timeout 408 The body of the request did not arrive in time and was not read. On POST /api/batches: the file took too long to arrive (Batches)
conflict 409 The state of the record does not allow the call
payload_too_large 413 The body or the file sent is larger than the API accepts. On POST /api/batches: the request is over the upload limit (Batches)
unsupported_media_type 415 The body is not of the kind the address takes. On POST /api/batches: a file is sent as multipart/form-data (Batches)
validation_error 422 The input is not valid. errors or details say which field
rate_limited 429 Too many calls of a kind that is limited per minute, or, on POST /api/batches, no room to read the file at the moment, uploads of the same key already waiting, or too many files arriving at the moment. Retry-After, when the answer has it, says how many seconds to wait
internal_error 500 An unexpected failure. The body also carries request_id
upstream_error 502 A service this API depends on failed or did not answer
service_unavailable 503 The function is not available at the moment

More specific codes may be added later (Versioning and changes). Treat a code you do not know like the status it came with.

An answer produced before the request reached the API (a 502, 503 or 504 during an outage or a release, or a refusal at the edge of the network) may have another body, or none, and no code: fall back on the HTTP status.

Status codes

Status When
200 The call succeeded
202 A lookup was created and is being classified in the background (Asynchronous work)
400 The request cannot be processed as sent
401 No valid API key was sent (Authentication)
402 The account that owns the work cannot be charged for it, or its free trial has ended and the account is read-only. Which of these can occur depends on the operation and on the account (Rate limits and quotas, A read-only account)
403 The role of the key, the plan of the account, or the workspace of the request does not allow the call (Workspace refusals)
404 The object does not exist, or belongs to another account and the key has the entry role
405 The address exists and does not take this method
408 The body of the request did not arrive in time and was not read. On POST /api/batches: the file took too long to arrive (Batches)
409 The state of the object does not allow the call: a batch that is already running, a decision that is not there to reopen
413 The body or the file sent is larger than the API accepts. On POST /api/batches: a body over the upload limit (Batches)
415 The body is not of the kind the address takes. On POST /api/batches: the file is not sent as multipart/form-data (Batches)
422 The input is not valid: a field failed validation, or a rule of the operation was not met. A file only a little over the upload limit, or whose text or column names are too long, is also answered 422
429 Too many requests of a kind that is limited per minute, or an upload that found the service busy reading other files, or that came while the same key already had uploads waiting, or while too many files were arriving (Batches)
500 An unexpected error on our side. The body carries a general message, code and request_id
502 A service the call depends on did not answer: the classification engine or an official source
503 A function is not available at the moment

A lookup that fails while it is being classified is not an HTTP error: the lookup ends with the status error and a message in its error field (Asynchronous work).

Validation errors

When a field of the request fails validation, the answer is 422 with one entry per field:

{
  "detail": "Invalid input",
  "code": "validation_error",
  "errors": [
    { "field": "description", "message": "String should have at least 1 character" }
  ]
}

field is the path of the field in the request (items.0.sku for the first item of a list). The message of an entry comes from the validation library and is in English.

When a rule of the operation is not met, the answer is also 422, with detail alone or with details:

{ "detail": "Enter the code to finalize", "code": "validation_error" }

A webhook URL that is refused names the field and the reason: "details": { "field": "url", "reason": "webhook_private" }.

State conflicts

{ "detail": "The lookup is not finalized", "code": "conflict" }

409 means the request was understood and the object is in a state that does not allow it. Read the object again before deciding what to do.

Plan refusals

A feature the plan of the account does not include, or a limit it would exceed, answers 403 with the code plan_feature or plan_limit and a details object that names the entitlement. The code is repeated in details.code, where it was before code existed:

code Fields of details Meaning
plan_feature key The plan does not include the feature key (for example feature.webhooks)
plan_limit key, limit, requested The call would make requested, and the plan allows limit (for example batch_max_rows)

GET /api/plans/me lists what the plan allows (Usage). It also says, in trial and read_only, whether the account is read-only (see below).

When the free trial of an account ends, the account is read-only. Reading and exporting still work, and so do the settings of the account. A new lookup, and every operation that changes something, is answered 402 with the code trial_ended:

{
  "detail": "Your free trial ended on 2027-01-15 (UTC). The account is read-only: you can still see your earlier lookups and the SKU catalog, but you cannot run a new lookup or make changes. You can write to us through the contact form.",
  "code": "trial_ended",
  "details": {
    "trial_ended_at": "2027-01-15T09:30:00+00:00",
    "trial_days": 14,
    "read_only": true
  }
}

details.trial_ended_at is a time with its offset from UTC, details.trial_days the length of the trial in days. The operations that can answer it declare a 402 in the OpenAPI document: 16 of them, listed in the changelog for 2026-10-05. The webhook operations are not among them. The refusal comes once the key and its role are accepted, before the fields of the request are checked and before a record is looked up: an unknown id or an invalid field on a read-only account is answered 402, not 404 or 422.

Starting a batch, retrying it and editing one of its rows start work that runs for the account that owns the batch. When that is another account, which a key with the reviewer or admin role can reach, and its trial has ended, the answer is 402 with the code owner_trial_ended:

{
  "detail": "The free trial of the account that owns this batch has ended and that account is read-only: no new work can be started on its batches.",
  "code": "owner_trial_ended",
  "details": {
    "read_only": true
  }
}

It says nothing about when the trial ended: the dates of a trial are told to its own account only. The same batch, started by its owner, is answered trial_ended.

A key acts as the account that created it. Only an administrator creates a key, and an administrator account is not on a trial, so a key does not normally receive trial_ended; it can after the account that created it has lost the administrator role. While workspaces are switched on, the trial is the workspace's: when it has ended, every member and every key of the workspace is answered trial_ended, with the workspace's date. GET /api/plans/me tells an account before it is refused: read_only is true once the trial has ended, and trial holds its dates (Usage).

Workspace refusals

While the service has workspaces switched on, a key acts in its own workspace (Authentication), and five codes say why a call was refused for that reason. None of them is answered while workspaces are switched off. Do not retry them: the same call is refused again until the key or the workspace changes.

code Status When
session_required 403 POST /api/webhooks, or a PATCH /api/webhooks/{hook_id} that sends url, made with a key. A person signed in to the application does these
workspace_mismatch 403 The request sends the header X-HTS-Workspace with anything but the id of the key's own workspace. A key does not need the header
member_suspended 403 The membership of the key's creator in the key's workspace is suspended
workspace_required 403 The key acts nowhere: its creator is no longer an active member of the workspace, or the workspace was closed or suspended. Create a new key in a workspace in use
workspace_not_found 404 The workspace of the request cannot be found

A record of another workspace is answered 404 with not_found, as if it did not exist.

detail follows the Accept-Language header of the request, and the answer names its language in Content-Language:

curl -i https://htspilot.com/api/usage/me -H "Accept-Language: vi"
HTTP/1.1 401 Unauthorized
Content-Language: vi
X-Request-ID: fbefced8d1434ceb9407bf612a8b008b

{"detail":"Vui lòng đăng nhập","code":"unauthenticated"}

Handling errors

  • Treat 401 and 403 as configuration problems: do not retry them.
  • 402 with out_of_credits: stop sending work that creates lookups until the account can be charged again. Do not retry it.
  • 402 with trial_ended: the account is read-only. Every write is refused, not only lookups: uploads, SKU changes, decisions and alert acknowledgements as well. Stop sending them, do not retry, and do not poll for it to change; reads still work. Read GET /api/plans/me to see the state of the account.
  • 402 with owner_trial_ended: the batch belongs to another account whose trial has ended. Do not retry; the same call is refused again.
  • 404, 409, 422: fix the request; the same request will fail again.
  • 408: on an upload, do not retry automatically. The same file over the same connection is likely to be too slow again. A person, or the program that calls, decides: a faster connection, or a smaller file. Sending again is safe, because nothing was stored (Batches).
  • 413: do not retry; the same file is refused again. Read max_upload_mb from GET /api/limits and split the file (Batches).
  • 415: a defect of the client. Fix how the request is built, a form with the field file, and do not retry (Batches).
  • 429: wait the number of seconds in Retry-After when the header is there, a minute when it is not, then retry. For an upload (POST /api/batches) the answer means the file was not read and no batch was created: send the same upload again after the wait, a bounded number of times, with a request timeout above 90 seconds plus the time your connection needs to send the file (Batches). An upload answered 429 at once means that the same key already has uploads waiting or arriving, that the line is full, or that the service has as many files arriving as it takes: send the uploads of one key one after the other.
  • 500, 502, 503, 504 and network errors: retry with a growing pause, and log X-Request-ID. Reads are safe to repeat. Before repeating a call that creates something, check whether the first one went through: there is no idempotency key, so a repeated POST /api/classify creates a second lookup, which can be charged a second time. POST /api/skus, and POST /api/skus/bulk without classify_missing, update an existing SKU and are safe to repeat; with classify_missing, a repeat classifies again every SKU that still has no code.