> ## Documentation index
> Fetch the complete documentation index at: https://docs.htspilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

> This page describes the API as of 2026-10-05. The service runs the latest version: https://docs.htspilot.com/errors.md

# 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

```json
{ "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](/v/2026-10-05/languages.md)) and its wording can
change. Every answer also carries the header `X-Request-ID` ([Request identifiers](/v/2026-10-05/request-identifiers.md)).

## 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](#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 |
| `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](/v/2026-10-05/batches.md#a-file-that-arrives-too-slowly-408)) |
| `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](/v/2026-10-05/batches.md#a-file-that-is-too-large-413)) |
| `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](/v/2026-10-05/batches.md#a-body-that-is-not-a-file-415)) |
| `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](/v/2026-10-05/versioning.md)). 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](/v/2026-10-05/asynchronous-work.md)) |
| `400` | The request cannot be processed as sent |
| `401` | No valid API key was sent ([Authentication](/v/2026-10-05/authentication.md)) |
| `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](/v/2026-10-05/rate-limits.md#credits), [A read-only account](#a-read-only-account)) |
| `403` | The role of the key, or the plan of the account, does not allow the call |
| `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](/v/2026-10-05/batches.md#a-file-that-arrives-too-slowly-408)) |
| `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](/v/2026-10-05/batches.md#a-file-that-is-too-large-413)) |
| `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](/v/2026-10-05/batches.md#a-body-that-is-not-a-file-415)) |
| `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](/v/2026-10-05/batches.md#an-upload-that-waits-429)) |
| `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](/v/2026-10-05/asynchronous-work.md)).

## Validation errors

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

```json
{
  "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`:

```json
{ "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

```json
{ "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](/v/2026-10-05/usage.md)). It also says, in `trial` and `read_only`,
whether the account is read-only (see below).

## A read-only account

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`:

```json
{
  "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](/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`:

```json
{
  "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. `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](/v/2026-10-05/usage.md#the-plan-object)).

## Language of the messages

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

```bash
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](/v/2026-10-05/batches.md#a-file-that-arrives-too-slowly-408)).
- `413`: do not retry; the same file is refused again. Read `max_upload_mb` from `GET /api/limits` and split the
  file ([Batches](/v/2026-10-05/batches.md#a-file-that-is-too-large-413)).
- `415`: a defect of the client. Fix how the request is built, a form with the field `file`, and do not retry
  ([Batches](/v/2026-10-05/batches.md#a-body-that-is-not-a-file-415)).
- `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](/v/2026-10-05/batches.md#an-upload-that-waits-429)). 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.
