Skip to Content
Baseera Docs

Errors

BaseeraError, the protocol error codes, and how to show them to end users.

Every client method throws BaseeraError when it fails. A stream yields an error event instead of throwing, once a turn has started.

import { BaseeraError } from "@baseera/core";

try {
  await client.startSession({ locale: "ar" });
} catch (error) {
  if (error instanceof BaseeraError) {
    console.error(error.code, error.status, error.retryAfter);
  } else {
    throw error;
  }
}

BaseeraError

Prop

Type

ClientErrorCode is every protocol code plus two the client raises itself: network_error (the request failed, or a stream failed twice) and invalid_response (the response was not what the protocol says).

Protocol codes

CodeHTTPMeaning
invalid_request400The body does not match the protocol, or a tool uses a reserved name (knowledge.search).
message_too_large413The message is over 8,000 characters.
too_many_tools400More than 64 tools, or duplicate names.
context_too_large413context.data is over 4 KB.
invalid_key401The publishable key is unknown or revoked.
invalid_user_token401The token is missing (outside dev mode), malformed or badly signed.
invalid_server_token401A server token was refused. Only on server-to-server endpoints.
user_token_expired401The token expired. The SDK fetches a new one and retries once.
origin_not_allowed403The page's origin is not in the agent's allowed domains.
agent_not_configured409The agent has no provider key or model.
session_not_found404No such session for this agent and user.
turn_not_found404No such turn in this session.
turn_in_progress409The session already has a running turn.
unknown_call_id409A result for a call id the turn did not make.
call_already_answered409A result for a call id that already has one.
source_not_found404The source cannot be opened: not cited by that message, private, removed, or not available to this user.
rate_limited429Over a rate limit. See retryAfter.
limit_reached429A spending limit is full: the agent's monthly limit, or the organization's default per tenant. There is no retryAfter; it resets on the 1st of the month (UTC) or when the owner raises it.
provider_key_missing502The agent's provider key was deleted.
provider_key_invalid502The provider rejected the key.
provider_out_of_credit502The provider says the key is out of credit.
provider_rate_limited502The provider rate limited the key. retryAfter when known.
provider_model_unavailable502The key cannot use the agent's model.
provider_context_too_long413The conversation is longer than the model accepts.
provider_error502Any other provider failure, including timeouts.
internal_error500An unexpected failure on Baseera's side.

The runtime also uses codes for server-to-server and eval calls, such as knowledge_base_not_found, eval_not_found, eval_run_in_progress, eval_limit_reached, idempotency_conflict, cost_confirmation_required, tenant_uploads_disabled and knowledge_quota_exceeded. All are in ERROR_CODES.

ERROR_STATUS maps each code to its status, ERROR_CODES lists them, and isErrorCode(value) is a type guard.

ProtocolError in a stream

interface ProtocolError {
  code: ErrorCode;
  message: string; // for developers
  retryAfter?: number; // seconds
}
for await (const event of turn) {
  if (event.type === "error") handle(event.error.code, event.error.retryAfter);
}

Show errors to users

Never show message to an end user. Map the code to your own text. The default surface does this for you, and you can reuse its mapping:

import { friendlyError } from "@baseera/ui/connected";
import { getSurfaceLabels } from "@baseera/ui";

const text = friendlyError(error.code, getSurfaceLabels("ar"));

It returns a short line for provider_out_of_credit, provider_rate_limited, agent_not_configured, network_error, rate_limited and limit_reached, and a generic one for any other code.

Log without leaking

Pass errors through redactForLog before they reach a logger. See Logging safely.

Next steps

On this page