> For the complete documentation index, see [llms.txt](https://docs.claret.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.claret.app/api-guide/errors.md).

# Error Reference

The Claret API reports errors using [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457) "Problem Details for HTTP APIs". Error responses use the `application/problem+json` content type and a consistent body shape.

## Error format

```json
{
  "type": "https://httpstatuses.com/422",
  "title": "Validation Error",
  "status": 422,
  "detail": "The request parameters are invalid.",
  "request_id": "5f8a1c2e-...",
  "errors": {
    "data.0.quantity": ["The quantity field must be a number."]
  }
}
```

| Field        | Always present | Description                                                            |
| ------------ | -------------- | ---------------------------------------------------------------------- |
| `type`       | Yes            | A URI identifying the problem type.                                    |
| `title`      | Yes            | A short, human-readable summary of the problem.                        |
| `status`     | Yes            | The HTTP status code, repeated in the body.                            |
| `detail`     | Yes            | A human-readable explanation specific to this occurrence.              |
| `request_id` | Yes            | Correlates the error with server logs. Include it in support requests. |
| `errors`     | No             | Field-level validation messages, present on `422` responses.           |

{% hint style="info" %}
Every response also carries an `X-Request-ID` header. When reporting a problem to support, include the `request_id` so the exact request can be traced.
{% endhint %}

## Status codes

### Success

| Code           | Meaning                             | Notes                                                       |
| -------------- | ----------------------------------- | ----------------------------------------------------------- |
| `200 OK`       | Request succeeded.                  | Synchronous reads and writes.                               |
| `201 Created`  | Resource created.                   | Token creation.                                             |
| `202 Accepted` | Work accepted for async processing. | Compute and workflow endpoints. Returns a `job_id` to poll. |

### Client errors

| Code  | Title                | What it means                                                                                          | How to resolve                                                                                                                         |
| ----- | -------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Bad Request          | The request was malformed (for example, invalid JSON).                                                 | Check the request body and query string syntax.                                                                                        |
| `401` | Unauthorized         | The token is missing, malformed, or revoked.                                                           | Send a valid `Authorization: Bearer {token}` header. Create a new token if it was revoked. Ensure `Accept: application/json` is set.   |
| `402` | Insufficient Credits | The tenant's credit balance cannot cover the request.                                                  | Wait for the monthly credit refresh, or contact support. See [API Credits & Usage](/api-guide/credits-and-usage.md).                   |
| `403` | Forbidden            | The token lacks the required scope, **or** the token creator lacks module permission for the resource. | Create a token with the [required scope](/api-guide/scopes.md), or provision it from a user who can see the resource in the Claret UI. |
| `404` | Not Found            | The resource or route does not exist.                                                                  | Check the URL, the `{tenant}` segment, and the resource ID.                                                                            |
| `409` | Conflict             | A conflicting operation is already in progress, or a duplicate request was detected.                   | For imports, wait for the in-progress job to finish. For retries, reuse the same `Idempotency-Key`.                                    |
| `422` | Validation Error     | The payload failed validation.                                                                         | Read the `errors` object for field-level messages and correct the input.                                                               |
| `429` | Too Many Requests    | A rate-limit bucket is empty.                                                                          | Wait the number of seconds in the `Retry-After` header, then retry with backoff. See [Rate Limiting](/api-guide/rate-limiting.md).     |

### Server errors

| Code  | Title               | What it means                                                                     | How to resolve                                                                          |
| ----- | ------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `500` | Server Error        | An unexpected error occurred.                                                     | Retry after a short delay. If it persists, contact support with the `request_id`.       |
| `503` | Service Unavailable | A dependency (such as the rate-limit or credit store) is temporarily unavailable. | Retry after a short delay. This is rare; the API is configured to fail open by default. |

## Validation errors in detail

`422` responses include an `errors` object keyed by the field path that failed. For array payloads (such as workflow sync), the path includes the row index:

```json
{
  "type": "https://httpstatuses.com/422",
  "title": "Validation Error",
  "status": 422,
  "detail": "The given data was invalid.",
  "request_id": "5f8a1c2e-...",
  "errors": {
    "data.0.item_name": ["The item name field is required."],
    "data.2.uom": ["The selected uom is invalid."]
  }
}
```

Use the index to locate the offending record in your payload.

## Related documentation

* [Authentication & Tokens](/api-guide/authentication.md) — resolving `401` and `403`.
* [Scopes Reference](/api-guide/scopes.md) — resolving scope-related `403`.
* [API Credits & Usage](/api-guide/credits-and-usage.md) — resolving `402`.
* [Rate Limiting](/api-guide/rate-limiting.md) — resolving `429`.