Troubleshooting requests and promotions

When a request fails, use its HTTP status and public error body to decide what to do next. The response does not expose database rows, credentials, provider locators, or internal cleanup details.

Authentication and visibility

• 401 unauthorized means the session or API credential was missing, expired, or invalid. Authenticate again and retry the same request.
• 403 forbidden means the authenticated principal is known but does not have the operation or Project/Environment access required by the request. Ask an organization owner or Project administrator to grant the appropriate access; changing an identifier in the request does not grant access.
• 404 not_found is also the response for an inaccessible Organization, Project, Environment, Agent, or run. Treat it as not visible rather than assuming the resource was deleted or probing other identifiers.

Retrying a mutation

Mutating requests that accept an Idempotency-Key use that key as the identity of one user action. Retry a timed-out or transient request with the same key. If the same key is sent with a different body or target, the API returns a 409 conflict; use a new key only for a genuinely new action. Do not generate a new key for every network retry.

Releases, Deployments, and Activation

A Release records exact immutable Agent and Definition revision pins. A Deployment materializes that Release for one Environment configuration and may remain queued while it validates or materializes. A failed Deployment is a terminal record with its public diagnostics; create a new Deployment from the intended Release after correcting the cause rather than editing the failed record.

Activation is separate: wait for the exact Deployment to be ready, then activate it using the Environment's current generation. A generation conflict means another activation won; reload the Environment, select the intended ready Deployment, and retry with the newly observed generation. Activation does not make a queued or failed Deployment active.

Deletion and cleanup

Organization, Project, and Environment deletion requests are asynchronous. The accepted response fences the resource in its deleting state and cleanup continues through the durable lifecycle. Disable further edits or promotion attempts while it is deleting and poll the public resource/list view rather than trying to delete it repeatedly. A transient queue or service failure can be retried with the original idempotency key.

Connections and provider configuration

Connections and provider settings select exact stored versions. A credential or BYOK failure should be corrected by selecting or authorizing the intended same-organization version; never put a secret in a request or documentation. Provider settings are optional: an empty provider-settings collection means the platform default. Do not add a dummy provider setting just to make the default work.

Cursors and changing ranges

Cursors are scoped to the resource, filters, and authorization context. Keep a cursor with the exact query that produced it. If the range, filter, target, or authorization context changes, start a fresh page instead of reusing the old cursor. If a cursor has expired or an event checkpoint has been compacted, use the public rebaseline/restart flow indicated by the 409 response; do not treat an empty page as proof that history never existed.