Troubleshoot an Integration

Locate failed authentication, missing context, incomplete turns, unresolved writes, and missing delivery, then collect the evidence needed to recover.

Start with the last milestone you can prove: authenticated request, usable context, accepted turn, completed answer, confirmed external action, or recipient delivery. A later milestone cannot be inferred from an earlier one.

Start at the last verified milestone and investigate the next boundary before repeating work.

For Console sign-in, missing services, and session-start problems, use the Console walkthrough troubleshooting. For local installation and result-file issues, use the starter troubleshooting.

Find the Failing Boundary

Symptom	Check first	Next action
Authentication fails	API family, regional host, workspace/organization, credential scope and expiry	Use Choose Credentials to select the Platform, Classic, or Scribe access flow
A service or entity is not found	Exact workspace and supplied identifiers; source acceptance versus projection/queryability	Inspect Services and Entity Resolve; do not select an arbitrary production record
An SDK example does not compile	Package name, pinned version, lockfile, and Node version	Reproduce the starter with npm ci; distinguish SDK drift from a runtime failure
A turn returns an acknowledgement but no final answer	background_pending, delivery protocol support, and returned receipt	Follow web application delivery; an observer dashboard stream is not the per-chat delivery protocol
A connection drops after a turn was sent	Saved conversation ID and durable history	Read the conversation before resending; the original turn may have been processed
Approval is granted but the target did not change	Decision consumption, next supported turn, actual integration result, target read-back	Follow approval-gated writes; reconcile an ambiguous target result before retrying
A tool cannot be tested	Tool family, endpoint identifiers, test permission, and applicable test operation	Follow Tool Testing; its generic execute operation does not execute every tool family
An SMS reply never arrives	Registration/routing, suppression, send acceptance, exposed delivery evidence	Follow managed SMS testing; a created conversation is not a delivery receipt
A Scribe artifact is not ready	Correct deployment base, provider access, session mode, generation status, and review version	Follow Scribe; generation acceptance is separate from a ready artifact
A test succeeds but production fails	Selected versions, actual channel, source freshness, tool access, and runtime differences	Compare the deployment configuration and rerun the failing case on its intended path

Preserve Evidence Before Retrying

Platform and managed-channel requests can return 503 during maintenance. A successful health check does not establish that those operations are accepting work. Check the response and the agreed status or support channel; do not treat a send acknowledgement, missing delivery receipt, or timeout as permission to send the same message again.

For an ambiguous request, keep the original identifiers and timestamp. Check durable state and the target system where applicable. A new conversation or retry can create new work; it is not a reconciliation mechanism.

Use the specific operation's retry guidance and exposed rate-limit information. There is no one platform-wide retry interval or rate limit. See SDK Error Handling and Rate Limits.

Prepare an Escalation

Send the responsible implementation or support contact the API/channel, region, workspace, UTC timestamp, SDK version, selected service/configuration, conversation/run identifier, available request identifier, expected milestone, and last observed result. Include a minimal synthetic reproduction and the relevant error/status when possible.

Describe whether the outcome is known to have failed or remains unknown, and what retries or manual actions have already occurred. Use the agreed secure support route for sensitive evidence. Do not paste credentials, private transcripts, or patient records into public documentation issues.

Verify Recovery

Repeat the smallest failing case, confirm the intended durable or external outcome, and confirm that retries did not create unintended duplicate work. Record the correction and add the failure case to the deployment's regression set. Close test conversations and reconcile pending actions using their owning lifecycle; closing a conversation does not undo a completed external write.