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

# Errors

> Reference Herm API error response bodies, HTTP status codes, validation failures, authentication problems, and common recovery steps.

API errors return a JSON body with an `error` code and a human-readable
`message`. Treat the HTTP status and `error` as the machine-readable contract.

## Error format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "error_code",
  "message": "Human-readable description of what went wrong"
}
```

## Error codes

| HTTP Status | Error Code             | Description                                                                                                                                    |
| ----------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| 400         | `validation_error`     | The request body or parameters are invalid                                                                                                     |
| 401         | `unauthorized`         | The API key is missing, invalid, or revoked                                                                                                    |
| 403         | `forbidden`            | The authenticated caller cannot perform the operation                                                                                          |
| 404         | `not_found`            | The requested resource does not exist in the authenticated organization                                                                        |
| 409         | `conflict`             | An optimistic concurrency check failed                                                                                                         |
| 409         | `invalid_state`        | The session state does not allow the operation — e.g. a prompt-starting `user.message` while a turn is running, or archiving a running session |
| 409         | `no_active_turn`       | The session is no longer waiting for the submitted control or tool-result event                                                                |
| 429         | `rate_limited`         | Too many requests — back off and retry                                                                                                         |
| 500         | `server_error`         | An unexpected error occurred on the server                                                                                                     |
| 502         | `server_error`         | An upstream credential or connector operation failed; retry only when the operation is safe to repeat                                          |
| 502         | `hermes_delete_failed` | Herm could not delete the session from the runtime; retry the session deletion                                                                 |
| 503         | `server_error`         | A required service is temporarily unavailable; retry with exponential backoff                                                                  |

Interpret `server_error` together with its HTTP status. A `500` is an unexpected
internal failure, a `502` identifies an upstream operation failure, and a `503`
is explicitly temporary and retryable.

## Validation errors

`400 validation_error` messages name the failing field path and the violated
constraint, one `path: constraint` entry per issue, separated by `;`. The
offending value is never echoed back.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "validation_error",
  "message": "events[0].content[0].text: Expected a string at most 20000 character(s) long"
}
```

## Common scenarios

### Missing API key

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.herm.run/v1/agents"
```

Returns `401 unauthorized` with `Invalid or missing API key`.

### Agent version conflict

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "conflict",
  "message": "Agent changed from version 2 to 3"
}
```

Fetch the agent again and retry the full update body with the latest
`expectedVersion`.

### Turn already in progress

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "invalid_state",
  "message": "A turn is already in progress"
}
```

A session runs one turn at a time. Either wait for the running turn to end, or
send the message with `delivery: "when_idle"` so Herm queues it and starts
it automatically once the session is idle — see
[Queue a message while a turn is running](/api-reference/send-message#queue-a-message-while-a-turn-is-running).

### Rate limits

Per-agent user limits return a structured `429` response:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "error": "rate_limited",
  "message": "Message limit reached.",
  "rateLimit": {
    "resource": "messages",
    "limit": 100,
    "remaining": 0,
    "periodSeconds": 60,
    "resetAfterSeconds": 17
  }
}
```

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
HTTP/1.1 429 Too Many Requests
Retry-After: 17
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 17
```

`resource` is `conversations` or `messages`. Wait at least the integer number of
seconds in `Retry-After` before retrying. Handle `rate_limited` explicitly in
your client.

Successful operations include `RateLimit-Limit`, `RateLimit-Remaining`, and
`RateLimit-Reset`. See
[Rate limits](/api-reference/rate-limits) for configuration and counting
behavior.

### Agent not found

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "error": "not_found", "message": "Agent not found" }
```