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

# Errors

> Error envelope format, all error codes, HTTP statuses, and retry guidance.

## Error format

All errors return a JSON body with a consistent structure:

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "agent_id is required",
    "request_id": "req_01j..."
  }
}
```

| Field              | Type   | Description                                                            |
| ------------------ | ------ | ---------------------------------------------------------------------- |
| `error.code`       | string | Machine-readable error identifier — use this for programmatic handling |
| `error.message`    | string | Human-readable description of the error                                |
| `error.request_id` | string | Unique request identifier — include when contacting support            |

***

## Error codes

| HTTP Status | `error.code`        | Description                                                                                                   |
| ----------- | ------------------- | ------------------------------------------------------------------------------------------------------------- |
| `400`       | `validation_error`  | Request body is malformed, missing required fields, contains unknown fields, or field values are out of range |
| `401`       | `unauthorized`      | Missing or invalid API key                                                                                    |
| `401`       | `forbidden`         | Valid API key, but it lacks the required scope for this endpoint                                              |
| `404`       | `not_found`         | Memory or resource does not exist, or belongs to a different organization                                     |
| `413`       | `payload_too_large` | `content` exceeds 8192 bytes, or the total request body exceeds the size limit                                |
| `429`       | `rate_limited`      | Key's request rate exceeded. Respect the `Retry-After` response header.                                       |
| `500`       | `internal_error`    | Unexpected server error                                                                                       |
| `503`       | `queue_unavailable` | Message queue temporarily unreachable (write path only)                                                       |

<Note>
  Both `unauthorized` (invalid key) and `forbidden` (missing scope) return HTTP `401`. Distinguish them by the `error.code` field.
</Note>

***

## Examples

### 400 Validation error

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "agent_id must match [A-Za-z0-9._:-]",
    "request_id": "req_01j..."
  }
}
```

Common causes: missing required fields, `agent_id` or `user_id` containing invalid characters, `k` out of range, `confidence` outside `0.0`–`1.0`, unknown fields in the request body.

### 401 Unauthorized

```json theme={null}
{
  "error": {
    "code": "unauthorized",
    "message": "invalid or missing api key",
    "request_id": "req_01j..."
  }
}
```

Your Bearer token is missing, malformed, revoked, or does not exist.

### 401 Forbidden (missing scope)

```json theme={null}
{
  "error": {
    "code": "forbidden",
    "message": "missing required scope: memory:write",
    "request_id": "req_01j..."
  }
}
```

Your API key is valid but was created without the required scope. Create a new key with the correct scopes in the dashboard.

### 413 Payload too large

```json theme={null}
{
  "error": {
    "code": "payload_too_large",
    "message": "content exceeds maximum length of 8192 bytes",
    "request_id": "req_01j..."
  }
}
```

### 429 Rate limited

```json theme={null}
{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded",
    "request_id": "req_01j..."
  }
}
```

Response headers: `Retry-After: 1` (seconds to wait before retrying). Both SDKs handle this automatically.

***

## Retry guidance

| Status              | Retry? | Notes                                               |
| ------------------- | ------ | --------------------------------------------------- |
| `400`               | No     | Fix the request body before retrying                |
| `401`               | No     | Fix the API key or scope                            |
| `404`               | No     | The resource does not exist                         |
| `413`               | No     | Reduce content size                                 |
| `429`               | Yes    | Wait `Retry-After` seconds, then retry              |
| `500`               | Yes    | Retry with exponential backoff                      |
| `502`, `503`, `504` | Yes    | Transient infrastructure issue — retry with backoff |