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

# Errors

> Error codes, which errors are worth retrying, and how a failed turn reports its cause.

## The error body

Every non-2xx response has the same body, and a `Request-Id` header to quote when you report a problem:

```json theme={null}
{
  "error": {
    "code": "invalid_request",
    "message": "spec.model: unknown model",
    "details": { "field": "spec.model" }
  }
}
```

| HTTP | `code` | When | Retry? |
| - | - | - | - |
| `400` | `invalid_request` | A malformed body or parameter; `details.field` names it | No: fix the request |
| `401` | `unauthorized` | A missing, unknown, revoked, or expired credential; `details.reason` says which | No: get a new credential |
| `403` | `forbidden` | The credential does not cover this resource, such as a session token outside its session | No |
| `404` | `not_found` | An unknown template version, agent, session, turn, entry, trigger, delivery, path, or CLI login code; `details.resource` names its kind | No |
| `409` | `conflict` | The request conflicts with the current state; `details.reason` says how | No: resolve the conflict |
| `413` | `payload_too_large` | A template document, system prompt, agent configuration, message, trigger request, or file over its limit; see [Limits](https://docs.paddock.build/platform/limits.md). Most other values over a limit are `400` | No |
| `422` | `unsupported` | A capability the agent's harness does not support; `details.capability` names it | No |
| `503` | `unavailable` | The agent's sandbox could not be woken in time, or a backing service is briefly unavailable | Yes, it is safe |
| `500` | `internal` | Anything else | Possibly |

### `details` you will see

| Code | `details` key | Values |
| - | - | - |
| `invalid_request` | `field` | A dotted path in the request, such as `ttlSeconds`, or `spec.mcp[github].url` in a template document |
| `invalid_request` | `errors` | Template validation: up to 50 `{ path, line?, message }` |
| `invalid_request`, `payload_too_large` | `reason` | `invalid_body`: the [trigger webhook](https://docs.paddock.build/api-reference/webhook.md) got a body that is not JSON or is over 1 MiB |
| `unauthorized` | `reason` | `missing`, `malformed`, `unknown_key`, `revoked`, `bad_signature`, `expired`, `session_deleted` |
| `not_found` | `resource` | `template`, `agent`, `session`, `turn`, `entry`, `path`, `model_provider`, `trigger`, `delivery`, `device_code` (a CLI login code that is unknown, expired, or already approved) |
| `conflict` | `reason` | `name_exists` (an entry or provider name that exists), `harness_changed` (a template version with another harness than its name), `template_in_use` (deleting a version an agent uses), `template_only` (deleting an entry only the template has), `model_in_use` (removing a model something names), `rejected` (replaying a rejected delivery), `precondition` (the operation conflicts with the agent's current state) |
| `unsupported` | `capability` | `mcp`, `plugins`, `workflows`, `memory`, `small_model`, or `harness` |
| `payload_too_large` | `limit`, `max` | The limit's name (`document_bytes`, `system_prompt_bytes`, `config_bytes`, `message_text`, or `request_bytes`) and its size in bytes; a file or a directory listing over its limit has no `details` |
| `internal` | `reason` | `outcome_unknown`: a `send` or `stop` failed after its write began, so it may be stored; look for its event in the session before trying again |

`details` is left out when it would be empty. The [trigger webhook](https://docs.paddock.build/api-reference/webhook.md)'s rejections, `invalid_body` and `bad_signature`, also carry `details.deliveryId`.

A code your SDK version does not know is kept as received.

## In the SDKs

```go Go theme={null}
_, err := client.Agents.Get(ctx, "agt_01h455vb4pex5vsknk084sn02q")
var apiErr *paddock.Error
var connErr *paddock.ConnectionError
switch {
case errors.As(err, &apiErr) && apiErr.Code == paddock.CodeNotFound:
	fmt.Println("no such agent; request", apiErr.RequestID)
case errors.As(err, &apiErr):
	fmt.Println(apiErr.Status, apiErr.Code, apiErr.Message, apiErr.Details)
case errors.As(err, &connErr):
	fmt.Println("no response:", connErr.Err) // wraps context.DeadlineExceeded on a timeout
}
```

```python Python theme={null}
import paddock

try:
    client.agents.get("agt_01h455vb4pex5vsknk084sn02q")
except paddock.PaddockError as e:
    print(e.status, e.code, e.message, e.details, e.request_id)
except paddock.TimeoutError:
    print("no response in time")
except paddock.ConnectionError:
    print("no response")
```

```ts TypeScript theme={null}
import { PaddockError, PaddockConnectionError } from "@paddock/server";

try {
  await paddock.agents.get("agt_01h455vb4pex5vsknk084sn02q");
} catch (e) {
  if (PaddockError.is(e)) console.log(e.status, e.code, e.message, e.details, e.requestId);
  else if (PaddockConnectionError.is(e)) console.log("no response");
  else throw e;
}
```

| Failure | Go | Python | TypeScript |
| - | - | - | - |
| A non-2xx response | `*paddock.Error` | `paddock.PaddockError` | `PaddockError` |
| No response | `*paddock.ConnectionError` | `paddock.ConnectionError` | `PaddockConnectionError` |
| No response in time | `*paddock.ConnectionError` wrapping `context.DeadlineExceeded` | `paddock.TimeoutError`, a `ConnectionError` | `PaddockTimeoutError`, a `PaddockConnectionError` |

An `error` event that ends a stream raises the same `PaddockError`, with the HTTP status of its code.

## Automatic retries

The SDKs retry idempotent requests (`GET`, `PUT`, `DELETE`) after a connection error, a timeout, or a `5xx`, up to 2 times by default with capped exponential backoff and jitter. Set `maxRetries` (`max_retries` in Python, `MaxRetries` in Go) to change it, `0` to turn it off.

A `POST` is never retried automatically, because it may have succeeded before the connection failed. After a failed `send`, look for the message in the session's events before sending it again. Streams reconnect on their own; see [Streaming](https://docs.paddock.build/guides/streaming.md#reconnection-and-expiry).

## Turn errors

A turn that fails does not fail any request: it ends with `status: "failed"` and an `error` on the turn and its `turn.ended` event, and the session shows it as `lastError` while it is `retrying` or `failed`.

| Turn error `code` | Means | The agent |
| - | - | - |
| `harness_error` | The harness could not start, exited, or reported an error | Retries |
| `watchdog_timeout` | No progress for 10 minutes, or 60 minutes while a tool call is open | Retries |
| `model_unavailable` | The model provider failed, was overloaded, or rate-limited the request | Retries |
| `model_auth` | The model endpoint refused the sandbox's credential, or your provider refused your key; see [Models](https://docs.paddock.build/guides/models.md#failures) | Retries |
| `context_too_long` | The conversation exceeds the model's context, even after the harness compacted it | Gives up |
| `conversation_lost` | The harness could not resume the session's conversation | Retries at once in a new conversation |
| `sandbox_unavailable` | The agent's sandbox could not be woken; the session is `blocked` | Keeps trying to wake it |
| `internal` | Anything else, such as an invalid working directory | Retries |

Unless the table says otherwise, a failed turn is retried up to two more times over the same messages, 10 seconds and then 60 seconds later; the retry's `attempt` is one higher. When the agent gives up, the session is `failed` and the waiting messages are held: the next message you send starts a turn that includes them. Messages sent while a retry is planned start a turn at once.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.