Guide

Debug Atlas integrations

Developers should be able to diagnose failures without guessing which plane broke. Collect identifiers first, then follow the specific recovery path for auth, execution, approval, webhook, RAG, or delivery failures.

request ID

Where: HTTP response headers, gateway logs, and API error bodies when present.

Use: Start every support ticket with the request ID and timestamp.

run ID

Where: Tool execution responses, shadow run lookup, run history, or approval metadata.

Use: Use the run ID to connect tool input, policy checks, approval records, and audit logs.

approval state

Where: GET /atlas/v1/approvals and approval decision responses.

Use: Differentiate pending, approved, denied, and expired work before retrying a mutation.

webhook delivery

Where: Webhook endpoint list, delivery attempts, event id, signature verification, and consumer logs.

Use: Confirm whether Atlas emitted, retried, or exhausted a webhook event.

replay path

Where: Idempotency key, webhook event id, delivery attempt id, and the original request payload.

Use: Replay only with the same idempotency key for the same payload; mint a new key for a new action.

error class

Where: Atlas error code plus retryable flag and available_alternatives in MCP errors.

Use: Route auth, validation, conflict, policy, upstream, and rate-limit failures to different recovery paths.

Failure triage order

  1. Check authentication and scopes before debugging tool behavior.
  2. Validate the payload against the generated OpenAPI contract.
  3. For RAG failures, require non-empty citations and reject gap_weak as a useful-answer failure.
  4. For mutations, inspect dry-run output, shadow run id, approval state, and idempotency key.
  5. For customer-visible messages, inspect outbox state, provider message id, delivery webhook, and replay path.
  6. For webhook consumers, verify signatures, event idempotency, retry history, and dead-letter handling.

Error classes

UNAUTHORIZED          refresh or replace credentials
FORBIDDEN             reduce requested scopes or re-consent
VALIDATION_ERROR      fix request body against generated contract
CONFLICT              idempotency payload mismatch
POLICY_BLOCKED        request approval or hand off
UPSTREAM_UNAVAILABLE  check Atlas config drift and service health
RATE_LIMITED          retry with backoff and same payload/key
EXECUTION_ERROR       inspect run ID, tool name, and audit logs