SDK errors and troubleshooting

An error tells you which step stopped and whether the operation might already have happened. A failed local definition can be corrected and validated again. A lost response to a call or booking needs a different response: check the existing operation before creating another one.

Handle an API error

The root client throws PlatformError. Read its structured fields rather than parsing its message:

typescript

import { PlatformError } from '@cumulus/sdk';

try {
  const agent = await client.agents.get({ path: { agent_id: agentId } });
  console.log(agent.name);
} catch (error) {
  if (!(error instanceof PlatformError)) throw error;
  console.error({ code: error.code, status: error.status, retryable: error.retryable });
  // Show a useful application error or retry this read with bounded backoff.
}

Here client is the configured Cumulus client and agentId is the agent to read. See API setup for client construction.

For a command, also inspect outcome and idempotencyKey. If outcome is unknown, the server may have accepted it. Retain the original request and key, read the corresponding resource, or replay that same request with the same key. A new key can create a second operation. Calls and results shows a persisted call command; API recovery covers edits and publications.

Error reference

Error	Meaning	Next step
`DefinitionError`	A definition or binding is invalid.	Correct the reported field and validate locally.
`DraftConflict`	The remote draft changed since review.	Export the draft, reconcile the change and preview again.
`PartialApplyError`	Some edits were applied before processing stopped.	Preserve the receipt and inspect the remote draft.
`PlatformError`	An API operation failed or its outcome is uncertain.	Inspect `code`, `status`, `retryable`, `outcome`, `details` and `idempotencyKey`.
`WaitTimeout`	A bounded wait ended.	Read current state; the call or artifact may still be processing.
`AuthenticationError`	Your customer endpoint rejected authentication.	Check the matching secret version, scheme and original request bytes.
`ToolOutcomeUncertain`	Your business operation may have completed.	Reconcile its persisted effect identity and result.
`TokenizationDeclined`	The vault definitely refused without creating a token.	Follow the private workflow's declined path.

Studio collaboration and recovery explains conflict and interrupted-publication handling. Customer HTTP adapters explains endpoint responses.

Diagnose a problem

Symptom	Check
Package will not install	The package archive/version and package-registry credentials. A Cumulus API key does not grant npm access.
Binding is missing	The selected environment supplies every referenced endpoint, notification and imported-number alias.
API returns `401` or `403`	API URL, key expiry, selected environment and required role.
Publication is refused	The returned diagnostics, model/provider configuration and required native settings.
Draft conflicts with Studio	Export the public draft and reconcile it with your source before adopting its revision.
Tool endpoint returns `401`	Binding and backend have matching secret bytes/version and authentication scheme.
Signature verification fails	The route receives original bytes before JSON parsing and uses the correct event/tool signature protocol.
Tool request lacks a run ID	`call.run_id` identifies the API run; `call.call_id` identifies the conversation. Require the run ID if the workflow depends on it.
Tool request repeats	Look up the durable effect receipt; return the saved result for the same input.
Recording or analysis is missing	Read that resource's state separately from the run's terminal state.
A phone call is silent or transfer fails	Inspect that run's recording, transcript and tool effects, then check the carrier/media setup.

When asking for help, include the sanitized agent/run ID, publication version, error code and approximate time. Keep keys, personal numbers, private digits and signed recording links out of shared reports.

Content version 73ee042aCustomer SDKMarkdown source