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

# Errors and retries

> Read documented API failures, respect recovery boundaries, and avoid duplicating a write.

Use the status code and machine-readable response fields to decide what to do
next. Do not branch on a human-readable error sentence or assume that a timed
out write failed.

<Note>
  **Preview.** The published OpenAPI operation remains the authority for its
  response codes and any endpoint-specific retry behavior.
</Note>

## Read the response body

Most Registry, Skill, Agent, File, and MCP failures use an
`application/problem+json` body with `title`, `status`, `detail`, and stable
`code`. Preserve `trace_id` when it is present. OTLP ingestion instead returns
its documented JSON error shape with `code`, `message`, and `details`.

Log the status, stable code, operation, and trace ID when available. Do not log
the bearer credential, request body, or a bundle's contents.

## Recover by status

| Status | Read and act                                                                                                                                                                              |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | The credential is missing, invalid, expired, or cannot resolve an identity. Refresh or replace it through the approved access process, then repeat a read.                                |
| `403`  | The resolved identity lacks access or the account is unavailable. Check the intended account and workspace, then request access. Do not change a workspace handle to bypass the boundary. |
| `404`  | The resource is absent or not visible in the resolved scope. Re-read a known parent or list operation in the intended scope. Do not infer that a different workspace owns it.             |
| `409`  | The request conflicts with current state. Read the returned or referenced resource and decide whether the existing state already satisfies the job.                                       |
| `412`  | A conditional write used stale state. Re-read the resource, review the new version or content hash, then construct a new intended write.                                                  |
| `422`  | The request was understood but failed validation. Correct the named field or package; retry only after the input changes.                                                                 |
| `429`  | The endpoint is rate limited. Honor `Retry-After` when the response includes it. Otherwise use bounded backoff and stop when the request deadline expires.                                |
| `5xx`  | The service could not complete the request. Treat a write outcome as unknown until you can read the relevant resource or use the endpoint's documented idempotency mechanism.             |

## Retry writes deliberately

Safe retries depend on the operation. For example, OTLP ingestion accepts
`X-Atlan-Ingest-Id` to identify the same batch on a retry. Skill uploads can
return the existing head when the bundle is byte-identical, but callers should
still read the resulting Skill and version before moving on.

Do not add a generic retry loop around every `POST`, `PATCH`, or archive call.
If a write times out or returns a 5xx response, read the intended resource first
and retry only when the endpoint contract makes the next action safe.

## Get help without exposing data

For a CLI trace issue, create a support bundle and inspect it before sharing:

```bash theme={null}
atlanai trace support bundle ./atlanai-support.json
```

For an HTTP request, share only the operation, status, stable error code, and
trace ID where your support process permits it. Keep tokens, full request
bodies, and customer content out of tickets and chat.