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

# Status and error codes

> HTTP statuses the API returns and what to do about them.

| Status                  | Meaning                                                                                                                                      | What to do                                            |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
| `200 OK`                | Request succeeded                                                                                                                            | —                                                     |
| `201 Created`           | Resource created                                                                                                                             | —                                                     |
| `400 Bad Request`       | Validation failed                                                                                                                            | Fix the fields named in `message`                     |
| `401 Unauthorized`      | Missing, invalid, or expired token                                                                                                           | Mint a new token                                      |
| `403 Forbidden`         | Token lacks the required scope, its organization doesn't match the partner subdomain, or the feature isn't enabled for the requested country | Check scopes; call the workspace the token belongs to |
| `404 Not Found`         | Resource doesn't exist in this workspace                                                                                                     | Check the ID — IDs from another partner always 404    |
| `422 Unprocessable`     | The request was valid but couldn't be fulfilled (unclassifiable input, a validation-rule rejection on create)                                | Read `message` / `errors`                             |
| `429 Too Many Requests` | Rate limited                                                                                                                                 | Back off and retry with the `Retry-After` header      |
| `5xx`                   | Something went wrong on our side                                                                                                             | Retry with exponential backoff                        |

## Error body

Errors are the mirror image of the success envelope — `success: false` with
a human-readable `message`:

```json 401 theme={null}
{ "success": false, "message": "Missing bearer token" }
```

```json 403 theme={null}
{ "success": false, "message": "Missing scope: classify:read" }
```

```json 403 theme={null}
{ "success": false, "message": "Duty calculation is not enabled for XX" }
```

```json 404 theme={null}
{ "success": false, "message": "Not found" }
```

Schema validation failures respond `400` with the failing messages joined
into `message`:

```json 400 theme={null}
{
  "success": false,
  "message": "country must be a 2-letter code"
}
```

One exception: when a **calculate** request is rejected by your workspace's
country validation rules, the `400` body is an `errors` array naming each
failed rule:

```json 400 theme={null}
{
  "errors": [
    { "code": "US_MAX_VALUE", "description": "Line value exceeds the configured limit" }
  ]
}
```

<Note>
  `404` is also the answer for resources that exist but belong to another
  partner — the API never reveals whether an ID exists outside your
  organization.
</Note>