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

# Errors and retries

> Retry safely, stop on permanent errors, and send useful support context.

Read the error code before retrying. Some failures are safe to retry. Others
need a change first.

Millwork uses a standard structured error response (`application/problem+json`).
Read `type`, `title`, `status`, `detail`, and `instance`. Do not display raw
provider errors to end users. Match the final path segment of `type` when you
need an exact API error identifier; human messages may improve over time.

## Safe retry rules

* Retry a failed write request with the same `Idempotency-Key` and identical body.
* Reusing a key with a different body returns `idempotency_conflict`.
* For `429`, wait for `Retry-After` or `retry_after_s`.
* Do not retry invalid credentials or denied permissions unchanged.
* For a run that fails after acceptance, read its status, events, then receipt.

## Common errors

| What happened                         | Error code             | What to do                                            |
| ------------------------------------- | ---------------------- | ----------------------------------------------------- |
| A field is invalid                    | `validation_failed`    | Correct the named field before retrying.              |
| The account cannot fund another run   | `insufficient_credit`  | Add credit before submitting another live run.        |
| A retry changed the request body      | `idempotency_conflict` | Use the original body, or use a new key for new work. |
| The API key is missing or rejected    | `unauthenticated`      | Check the bearer header or replace the key.           |
| The caller cannot perform this action | `permission_denied`    | Use the correct role or a human dashboard session.    |
| Requests are arriving too quickly     | `rate_limited`         | Wait for the stated delay.                            |

Provider connection reasons such as `authentication`, `permission`, and
`model_not_found` have a separate recovery path. Read
[Provider connection help](/help/provider-connections).

Run reasons such as `no_eligible_arms` appear in events and receipts rather
than as the API problem type. Read [Run and result help](/help/runs).

## Ask for help

Include the `instance` value, endpoint, UTC time, `type`, and `title` in a
[email to support](mailto:support@getmillwork.dev). Never include secrets,
cookies, credential-flow URLs, prompts, or customer data.