Troubleshoot a failed integration

Start from the stable code, status, or result that your backend observed. Use this guide to collect safe evidence and choose a platform operation without logging credentials or sensitive inputs.

Start with the symptom

Authentication failures

Provider failures

When a key or Provider type changes, migrate the references as well as the current Agent:

1. Validate the new configuration with providers.test() or REST test Provider config, then save it with providers.create() or REST create Provider.
2. Enumerate all current Agents with agents.list() or REST list Agents. A shared Provider may appear only in history, so page every Agent's Versions with agents.listVersions() or REST list Agent Versions, and inspect each Version's providerId; checking only each Agent's current providerId is insufficient.
3. Find the Version resolved by each affected execution. For each Task with a non-null activeRunId, read that run with tasks.getRun() or REST get Task run. For a complete historical audit, page tasks.listRuns() or REST list Task runs to cursor exhaustion. Each run exposes agentVersion. For every Agent, also page sessions.list() or REST list Sessions to cursor exhaustion; pinned Sessions expose their configured agentVersion. Inspect each referenced immutable Version with agents.getVersion() or REST get Agent Version.
4. Point every affected current Agent at the replacement with agents.update() or REST update Agent. This creates a new Version; it does not rewrite historical Versions.
5. Page affected definitions to cursor exhaustion with tasks.list() or REST list Tasks. Use tasks.update() or REST update Task to set agentVersion to the replacement Version, or to null to follow latest.
6. A queued or running Task run keeps the Version resolved when it was enqueued, even after its Task Pin changes. Let old-Version runs reach a terminal state, or request cancellation with tasks.cancelRun() or REST cancel Task run, and verify the terminal result with the Task-run reads above.
7. A Session Pin cannot be changed. Start a replacement Session with the new Version through client.chat() or REST create a Session turn. Unpinned Sessions follow latest and do not need replacement.

Keep the old Provider while any historical Version Pin must remain usable. providers.delete() and REST delete Provider check current Agent references, not historical Versions. Deletion makes future Provider resolution fail for every remaining Task Pin, Session Pin, queued Task run, or explicit stateless Pin whose historical Version contains that ID. It does not revoke credentials already resolved and decrypted for an admitted Turn, so that Turn may finish. A Task run still before Provider resolution can become failed; its untyped error is not a stable code and must not be matched for an internal error name. A synchronous request instead exposes the public not_found HTTP 404. Preserve the drain-or-cancel procedure above and observe every old-Version run's terminal state before deleting the Provider.

Streaming failures

MCP failures

Sandbox failures

Normal Sandbox contention waits for durable admission; it does not return a busy error.

Task failures

Quota failures

Collect safe diagnostics

The SDK exposes code and optional HTTP status on BlazingAgentsError. Resource IDs and the REST response's X-Request-Id are safe correlation fields when they do not encode your own sensitive metadata.

import { BlazingAgentsError } from "@blazing-agents/sdk";

try {
  await client.tasks.get(taskId);
} catch (error) {
  if (!BlazingAgentsError.isInstance(error)) throw error;
  console.error({
    code: error.code,
    resourceId: taskId,
    status: error.status,
  });
}

Never log API keys, Provider credentials, MCP credentials, raw prompts, message parts, Tool inputs/results, or Sandbox file contents. Redact upstream messages before sharing them because the SDK's message is human-readable context, not a stable diagnostic code.

The example reads the definition with tasks.get(); the equivalent REST operation is get Task.

Related capabilities

• Security and credentials
• Models and Providers
• Generation and streaming
• MCP connections
• Sandboxes
• Tasks and schedules
• Usage and quotas
• Limits and reliability

SDK and REST reference

Use the canonical error contract for the wire envelope, SDK codes, statuses, and stream boundaries. The branch tables link the exact TypeScript SDK and REST operations used for each diagnostic and recovery action; the REST authentication contract explains the shared Bearer boundary.