Skip to Content
Baseera Docs

Errors

Every error code the runtime returns, with its HTTP status, what it means and how to fix it.

Before a stream starts, an error is a JSON response with an HTTP status. After the stream starts, the same body arrives as an error event, which is the last event of the stream.

{ "error": { "code": "rate_limited", "message": "Too many requests. Try again in 12 seconds.", "retryAfter": 12 } }

code is stable. Branch on it. message is for developers and can change. retryAfter (seconds) appears with rate_limited and provider_rate_limited, and rate limits also set the Retry-After header.

End users never see message. The SDK shows a short generic line and calls onError({ code, retryAfterMs? }) for you.

Error responses carry cache-control: no-store, and allow any valid origin so the SDK can read the code.

Request errors

CodeStatusMeaningFix
invalid_request400The body does not match the protocol, a limit was exceeded, or a tool uses a reserved name.Check the body against the endpoint's schema. Remove knowledge.search from tools.
message_too_large413Message over 8,000 characters, or a knowledge batch over 4,000,000 bytes.Shorten the message or split the batch.
too_many_tools400More than 64 tools, or duplicate names.Send fewer tools and give each a unique name.
context_too_large413context.data over 4 KB.Send less data in context.

Authentication errors

CodeStatusMeaningFix
invalid_key401Publishable key unknown or revoked.Copy the current key from the console.
origin_not_allowed403Origin is not in the agent's allowed domains.Add the domain in the agent's settings.
invalid_user_token401Token missing (outside dev mode), malformed, badly signed, wrong algorithm, wrong agent, or a server token.Sign with signUserToken and an sk_ key of this agent.
user_token_expired401A correctly signed token that has expired.Fetch a new token and retry. The SDK does this once.
invalid_server_token401Server token missing, malformed, badly signed, for another agent or purpose, or valid for over 60 seconds.Sign a fresh token with the right purpose and send x-baseera-agent.

State errors

CodeStatusMeaningFix
agent_not_configured409The agent has no provider key or model.Add a provider key and pick a model in the console.
session_not_found404No such session for this agent, user and tenant.Start a new session.
turn_not_found404No such turn in this session, or one that is not waiting for results.Use the turnId from turn.awaiting_tools.
turn_in_progress409The session already has a running turn.Wait for turn.done, or cancel the turn.
unknown_call_id409A result for a call id the turn did not make.Use the ids from turn.awaiting_tools.
call_already_answered409A result for a call id that already has one, including server calls.Answer each app call once.
source_not_found404The source cannot be opened: not cited by that message, private, removed, or not available to this user.Show the title only. Nothing more is revealed.
idempotency_conflict409An Idempotency-Key was already used for a different signal.Use a new key for different content.

Knowledge errors

CodeStatusMeaningFix
knowledge_base_not_found404The knowledge base does not exist or is not in the agent's organization.Copy the id from the console.
tenant_uploads_disabled403The agent's knowledge.tenantUploads setting is off.Turn it on in the agent's Knowledge page.
knowledge_quota_exceeded413The tenant reached 200 files or 200 MB.Delete files or ask for more room.

Eval API errors

CodeStatusMeaningFix
eval_not_found404The suite, target version or run does not exist for this agent.Check the suite name and target.
eval_run_in_progress409A run is already queued or running for this agent.Poll the active run, then start yours.
eval_limit_reached429A run is over 500 attempts, or the agent started 30 runs in the last hour.Reduce cases or repeats, or wait.
cost_confirmation_required400confirmCost was not true. The body also carries estimate. Nothing started.Resend with confirmCost: true.

Limit errors

CodeStatusMeaningFix
rate_limited429Over a rate limit.Wait retryAfter seconds.
limit_reached429A monthly spending limit is full. No retryAfter.Wait for the 1st (UTC) or raise the limit.

Provider errors

These come from the model provider behind the customer's own key.

CodeStatusMeaningFix
provider_key_missing502The agent's provider key was deleted.Add a key in the console.
provider_key_invalid502The provider rejected the key.Replace the key.
provider_out_of_credit502The provider says the key has no credit.Add credit with the provider.
provider_rate_limited502The provider rate limited the key. retryAfter when known.Wait and retry.
provider_model_unavailable502The key cannot use the agent's model (unknown, retired or not allowed).Choose another model.
provider_context_too_long413The conversation is longer than the model accepts.Start a new session.
provider_error502Any other provider failure, including timeouts. Retried once before any output.Retry later.
internal_error500A bug on our side.Retry, and report it if it persists.

When a key is invalid or out of credit, Baseera emails the organization's owners, at most once per key per 24 hours.

Other codes you may meet

These are not in the main error table. They appear inside a successful response, or in a different field.

Per-item knowledge rejections (inside a 200 push response): invalid_item, too_large, limit_reached, not_found, conflict, unavailable. See Knowledge.

Finish verification refusals (a 200 with ok: false): receipt_not_found, entity_mismatch, receipt_expired, receipt_used, override_required. See Other endpoints.

Webhook errorCode on knowledge.item.failed: parse_failed, no_text, too_large, unsupported_type, fetch_failed, blocked_url, invalid_key, no_credit, rate_limited, provider_error, timeout. See Webhooks.

Next steps

On this page