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:

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.

A new idempotency key is a new intent. It is not a generic retry flag.

Inspect and recover your work before starting a replacement run.