Errors

Blazing Agents exposes a closed public error-code set for HTTP failures and two additional SDK-local codes. Use stable codes and HTTP status for control flow; treat messages as human-readable context.

Contract

Pre-stream and non-streaming failures use the strict shape { error: { code, message, meta? } }.

meta is optional structured context. The SDK currently preserves code, message, and HTTP status on BlazingAgentsError; it does not expose envelope meta. Redact tenant-supplied values before logging metadata.

ApiErrorCode

API_ERROR_STATUS defines each code's canonical status. Some operations retain a more specific status while using the closest public code: state conflicts can be 409 with invalid_request, oversized/unsupported uploads can be 413 or 415 with invalid_request, and a deleted Artifact download is 410 with not_found. Preserve both status and code.

One raw REST operational exception exists outside this closed code set. While the API process is draining, lifecycle admission returns HTTP 503 with { "error": { "code": "SERVICE_UNAVAILABLE", "message": "Service unavailable" } }. SERVICE_UNAVAILABLE is not an ApiErrorCode; the SDK therefore normalizes that response to code: "internal" while preserving status: 503. Treat this as an API lifecycle boundary, not as an additional product error code.

Quota errors

quota_exceeded is returned by Turn-producing calls when the Tenant's self-set token or request ceiling is exhausted. See the Quota limits.

BlazingAgentsErrorCode

The SDK union contains every ApiErrorCode plus:

BlazingAgentsError extends Error and exposes name, code, message, optional status, and inherited cause. Prefer BlazingAgentsError.isInstance(error) to instanceof when bundles may contain multiple SDK copies.

The public constructor accepts { code, message, status? } and an optional standard ErrorOptions object such as { cause }. When logging an SDK error, record a coarse cause category—HTTP, network, or stream—from status and code. Do not log the raw cause until tenant-supplied and credential-bearing content has been removed.

If a proxy returns a non-envelope body, the SDK derives a code from the status, maps 410 to not_found, maps unknown statuses to internal, and uses the body as the human message.

Failures after streaming begins follow the streaming protocol: Session streams emit a native { "type": "error", "errorText": "safe prose" } chunk, while completion/object terminal consumption rejects with stream_error. A failed or canceled interactive Session Turn does not commit transcript changes, but arbitrary retry is not guaranteed side-effect safe because an external Tool call may already have run. Durable Tasks attach a fresh Session before execution and persist events incrementally, so a failed Task can retain user, assistant, and failure history.

For operational logs, record the HTTP status, stable code, X-Request-Id, and non-sensitive resource identifiers. Never log authorization headers, API keys, Provider credentials, or MCP credentials. There is no public Retry-After contract.

Examples

This envelope validates against apiErrorResponseSchema:

{
  "error": {
    "code": "invalid_request",
    "message": "Request body is invalid.",
    "meta": { "field": "agentId" }
  }
}

Branch on stable SDK codes and rethrow unknown errors:

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

function handleSdkError(error: BlazingAgentsError) {
  if (error.code === "quota_exceeded") return { retryAfterReset: true };
  if (error.code === "network_error") return { retryWithBackoff: true };
  if (error.code === "AGENT_DISABLED") return { enableAgent: true };
  throw error;
}

async function runTurn() {
  try {
    await client.chat({
      agentId,
      message: {
        id: "user-1",
        role: "user",
        parts: [{ type: "text", text: "Summarize the incident." }],
      },
    });
  } catch (error) {
    if (!(error instanceof BlazingAgentsError)) throw error;
    return handleSdkError(error);
  }
}

Await the final value to observe failure after a successful response started:

const result = await client.completion(input);

try {
  console.log(await result.text);
} catch (error) {
  if (BlazingAgentsError.isInstance(error) && error.code === "stream_error") {
    console.error("The Turn failed after streaming began.");
  } else {
    throw error;
  }
}

Used by

• SDK client
• SDK generation
• REST authentication
• REST generation
• REST Sessions
• Security and credentials
• Limits and reliability
• Troubleshoot a failed integration

Every SDK resource and REST endpoint page uses this error contract.

Source of truth

• packages/core/src/api.ts
• packages/core/src/api.test.ts
• servers/api/src/utils/error-envelope.ts
• servers/api/src/utils/error-envelope.test.ts
• servers/api/src/app.ts
• servers/api/src/app.test.ts
• packages/server-core/src/service-lifecycle.ts
• packages/server-core/src/service-lifecycle.test.ts
• packages/server-core/src/http.ts
• packages/sdk/src/errors.ts
• packages/sdk/src/errors.test.ts
• packages/sdk/src/http.ts
• packages/sdk/src/http.test.ts
• packages/sdk/src/generation.ts
• packages/sdk/src/generation.chat-errors.test.ts
• packages/sdk/src/generation.transport-errors.test.ts
• packages/sdk/src/generation.completion.test.ts
• packages/sdk/src/generation.object.test.ts
• servers/task-worker/src/task-run-execution.ts
• servers/task-worker/src/run-workflow-persistence.test.ts

Related guides

See the capability and guide links under Used by.

Reference

See the implementation inventory under Source of truth.