Source: https://docs.cumuluslabs.io/sdk-errors
Content version: 73ee042a

# 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](/docs/sdks#typescript) 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](/docs/sdk-runtime) shows a persisted call command; [API recovery](/docs/api#response-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](/docs/sdk-lifecycle) explains conflict and interrupted-publication handling. [Customer HTTP adapters](/docs/sdk-server) 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.