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.

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

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:

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.