> ## 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-04. 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-04/languages.md)) and its wording can
change. Every answer also carries the header `X-Request-ID` ([Request identifiers](/v/2026-10-04/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 |
| `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-04/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-04/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-04/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-04/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-04/asynchronous-work.md)) |
| `400` | The request cannot be processed as sent |
| `401` | No valid API key was sent ([Authentication](/v/2026-10-04/authentication.md)) |
| `402` | The account that owns the work cannot be charged for it. Whether this can occur depends on the account ([Rate limits and quotas](/v/2026-10-04/rate-limits.md#credits)) |
| `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-04/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-04/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-04/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-04/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-04/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-04/usage.md)).

## 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`: when it occurs, stop sending work that creates lookups until the account can be charged again. Do not
  retry it.
- `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-04/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-04/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-04/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-04/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.
