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

# Errors and retry safety

> Interpret customer API failures and recover without duplicating work.

Use the status code to choose your next step. An error does not prove that a submitted request did nothing: check the resource before retrying work.

| Status | Meaning | Default action |
| - | - | - |
| `401` | Credential is missing, expired, or invalid | Authenticate again. |
| `403` | Credential is valid but lacks user, organization, or operation scope | Change identity or scope; do not retry unchanged. |
| `404` | Resource is absent or hidden by permissions | Confirm the environment, owner, and ID. |
| `409` | Lifecycle, immutability, idempotency, or evidence conflict | Inspect current resource state before changing anything. |
| `413` | Package, file, or artifact is too large | Reduce or split the input. |
| `422` | Request or selector is invalid | Repair the payload; retries do not help. |
| `429` | Quota or write-rate decision | Respect `Retry-After` when present and inspect quota. |
| `502` | Synth could not complete the response | Inspect the resource; a submitted request may already have taken effect. |
| `503` | The requested operation is temporarily unavailable | Inspect current state and respect `Retry-After` when present. |
| `504` | The request timed out | Inspect the resource before deciding whether to retry. |

## Error envelopes vary by family

The customer API can return a string `detail`, a structured Registry error, or a validation array. Always log the status, request ID, error code when present, and redacted detail.

Do not log the bearer token, signed artifact URL, task archive contents, or raw private transcript.

## CLI identity errors

Common messages:

```text theme={null}
managed registry commands require a user credential. run `synth login` or set SYNTH_ACCESS_TOKEN
customer credential not found
```

Use `synth status --json` to check whether you are signed in and which API URL the CLI targets, without printing the token.

## Unknown outcome

Treat phrases such as `outcome unknown`, `may already exist`, or `inspect before retrying` literally. They mean the server may have committed state even though the response did not reach you.

For an operation that documents idempotent retries, preserve the original request and key. If the operation does not document that guarantee, do not automatically resubmit it. Keep the resource ID and request ID for troubleshooting.

<Warning>
  A new idempotency key is a new intent. It is not a generic retry flag.
</Warning>

[Inspect and recover your work](/operations/lifecycle-and-recovery) before starting a replacement run.


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