Know what failed before deciding what happens next.

Likely causes

• Missing or mismatched credential generation
• HTTP endpoint outside an explicit loopback test
• SDK initialized in the wrong lifecycle or with incompatible packages
• Release configuration differs from development

First checks

1. Choose the exact product/runtime authentication path
2. Compare safe endpoint host, SDK version, build variant, origin/package/bundle identity, and region
3. Confirm the provider request was never sent before retrying

Stateless

1. Correct configuration
2. Run one bounded non-production probe
3. Record the selected generation and release proof

Stateful

1. Keep the aggregate unchanged
2. Correct configuration
3. Reconcile any adapter queue before resuming commands

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Wrong coordinate order, field name, enum, timestamp unit, or bound
• Required field or content type missing
• Request built for another API or SDK generation
• A state transition precondition is not satisfied

First checks

1. Open the exact normalized operation rather than a neighboring guide
2. Validate method, host, path, auth generation, required fields, units, and maximums
3. For transitions, reload current state and allowed commands

Stateless

1. Fix the invalid field or contract selection
2. Add a regression test for the rejected boundary
3. Retry once with a new request identity if required

Stateful

1. Do not mutate local state optimistically
2. Reload the aggregate and allowed transition
3. Submit a corrected command with a stable idempotency key

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Current static key, legacy OAuth, InTouch bearer, app key, or MCP token was interchanged
• Credential expired, was rotated, or is not present in the intended runtime
• Host/path generation or Authorization transport is wrong
• Clock skew or issuer/audience mismatch

First checks

1. Stop automatic retries
2. Compare the selected authentication path and issued generation
3. Rotate only through the controlled overlap-and-drain lifecycle

Stateless

1. Correct credential selection or refresh through the approved provider
2. Prove one non-production request
3. Resume bounded traffic without logging token text

Stateful

1. Pause commands
2. Refresh or rotate identity
3. Reconcile queued and unknown outcomes before resuming

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Product or quota was not provisioned
• Origin, server egress, Android signing identity, iOS bundle/team, asset, or region does not match
• Human or service actor lacks transition authority
• MCP deployment profile or OAuth scope excludes the tool

First checks

1. Keep restrictions in place
2. Inspect entitlement and credential metadata in the console
3. Request the narrow missing access with product, environment, region, and business purpose

Stateless

1. Obtain or correct least-privilege entitlement
2. Prove the exact runtime restriction
3. Retry only after control-plane evidence changes

Stateful

1. Keep the command pending or rejected according to the journey
2. Record the decision trail
3. Resume only after entitlement activation is independently observed

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Wrong host/path or legacy/current generation
• Resource belongs to another tenant, region, project, or environment
• Identifier is stale, deleted, retired, or never committed
• Read-after-write convergence is still pending

First checks

1. Confirm exact resource type and environment
2. Use a supported list/read contract where available
3. For a recent write, reconcile by idempotency key or provider request ID

Stateless

1. Correct the identifier or endpoint generation
2. Do not enumerate foreign resources
3. Treat 410 as retired unless the contract says otherwise

Stateful

1. Reconcile command and event history
2. Distinguish pending convergence from terminal absence
3. Require a new command for recreation rather than silently reusing identity

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Optimistic version is stale
• An idempotency key was reused with different content
• The transition already completed or is no longer allowed
• Two actors attempted incompatible changes

First checks

1. Read the latest aggregate version and event/audit evidence
2. Compare a safe request-content digest—not the payload—against the original command
3. Decide whether the intended business outcome is already satisfied

Stateless

1. Correct the stale precondition
2. Use a fresh request identity only for a genuinely new operation
3. Never turn a conflicting duplicate into an automatic new write

Stateful

1. Reconcile current aggregate and provider state
2. Return the already-committed result when the original intent matches
3. Otherwise require an explicit new versioned command

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Burst or sustained rate exceeded
• Monthly entitlement or tenant delivery budget exhausted
• Retry storm or missing client-side coalescing
• One workload is starving others

First checks

1. Honor Retry-After when present
2. Inspect application/product usage and quota
3. Reduce concurrency, coalesce duplicate reads, and add jitter

Stateless

1. Wait for Retry-After or a bounded exponential backoff with jitter
2. Cap attempts and total elapsed time
3. Cache or batch where the contract permits

Stateful

1. Keep the command durably queued
2. Schedule a later attempt without changing idempotency identity
3. Preserve per-aggregate ordering and tenant fairness

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Client deadline too short
• DNS, TLS, proxy, mobile/offline, or provider connectivity failure
• Large or expensive request
• Response was lost after a stateful commit

First checks

1. Classify the operation safety before retrying
2. Retain request ID, idempotency identity, deadline, attempt, and occurrence time
3. Check service status and local network without exposing the request URL

Stateless

1. Retry an idempotent read within an attempt and elapsed-time budget
2. Use jitter and a fresh transport connection where appropriate
3. Surface a bounded unavailable result after exhaustion

Stateful

1. Mark outcome unknown
2. Query by provider request or idempotency identity
3. Retry the same command identity only when the contract proves idempotency

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Provider or gateway incident
• Upstream returned malformed or incomplete data
• Dependency saturation or rollout regression
• Regional routing or entitlement adapter unavailable

First checks

1. Check request diagnostics and public status
2. Compare error rate by operation, application, region, and release
3. Use request ID for provider correlation and keep response bodies out of tickets

Stateless

1. Use bounded exponential retry only for safe reads
2. Open a circuit after the retry budget
3. Serve an explicit stale/partial fallback only when product semantics permit

Stateful

1. Move the command to unknown or retry-scheduled state
2. Reconcile before reissuing
3. Preserve the same idempotency identity and ordering lane

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• Accepted asynchronous work has not completed
• Callback or webhook is delayed or missing
• Response was lost after commit
• Application and provider inventories disagree

First checks

1. Keep the original idempotency and provider request identities
2. Read aggregate, outbox, callback, delivery, and provider evidence
3. Escalate only a minimized support packet after the reconciliation deadline

Stateless

1. Do not use this class for a truly stateless read
2. Reclassify from the actual HTTP/error evidence

Stateful

1. Persist unknown outcome explicitly
2. Reconcile by stable identity
3. Apply the observed terminal event once
4. Require independent recovery approval where replay has material effect

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default

Likely causes

• SDK callback omitted a status
• A wrapper replaced the provider error
• Multiple generations use the same informal message
• Only human-readable text was captured

First checks

1. Capture a bounded status, code, runtime, operation, and request ID
2. Identify whether the action is a read or state change
3. Use the exact API/SDK guide and release version

Stateless

1. Do not retry until the operation and failure class are known

Stateful

1. Preserve state and mark outcome unknown
2. Reconcile before any replay

Never collect

• Keys, tokens, client secrets, Authorization headers, or signed URLs
• Full request URLs when a credential may be in the query string
• Customer payloads, precise-location history, media, or response bodies by default