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
| Code | HTTP | Meaning |
|---|---|---|
invalid_request | 400 | The body does not match the protocol, or a tool uses a reserved name (knowledge.search). |
message_too_large | 413 | The message is over 8,000 characters. |
too_many_tools | 400 | More than 64 tools, or duplicate names. |
context_too_large | 413 | context.data is over 4 KB. |
invalid_key | 401 | The publishable key is unknown or revoked. |
invalid_user_token | 401 | The token is missing (outside dev mode), malformed or badly signed. |
invalid_server_token | 401 | A server token was refused. Only on server-to-server endpoints. |
user_token_expired | 401 | The token expired. The SDK fetches a new one and retries once. |
origin_not_allowed | 403 | The page's origin is not in the agent's allowed domains. |
agent_not_configured | 409 | The agent has no provider key or model. |
session_not_found | 404 | No such session for this agent and user. |
turn_not_found | 404 | No such turn in this session. |
turn_in_progress | 409 | The session already has a running turn. |
unknown_call_id | 409 | A result for a call id the turn did not make. |
call_already_answered | 409 | A result for a call id that already has one. |
source_not_found | 404 | The source cannot be opened: not cited by that message, private, removed, or not available to this user. |
rate_limited | 429 | Over a rate limit. See retryAfter. |
limit_reached | 429 | A 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_missing | 502 | The agent's provider key was deleted. |
provider_key_invalid | 502 | The provider rejected the key. |
provider_out_of_credit | 502 | The provider says the key is out of credit. |
provider_rate_limited | 502 | The provider rate limited the key. retryAfter when known. |
provider_model_unavailable | 502 | The key cannot use the agent's model. |
provider_context_too_long | 413 | The conversation is longer than the model accepts. |
provider_error | 502 | Any other provider failure, including timeouts. |
internal_error | 500 | An 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.