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
| Code | Status | Meaning | Fix |
|---|---|---|---|
invalid_request | 400 | The 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_large | 413 | Message over 8,000 characters, or a knowledge batch over 4,000,000 bytes. | Shorten the message or split the batch. |
too_many_tools | 400 | More than 64 tools, or duplicate names. | Send fewer tools and give each a unique name. |
context_too_large | 413 | context.data over 4 KB. | Send less data in context. |
Authentication errors
| Code | Status | Meaning | Fix |
|---|---|---|---|
invalid_key | 401 | Publishable key unknown or revoked. | Copy the current key from the console. |
origin_not_allowed | 403 | Origin is not in the agent's allowed domains. | Add the domain in the agent's settings. |
invalid_user_token | 401 | Token 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_expired | 401 | A correctly signed token that has expired. | Fetch a new token and retry. The SDK does this once. |
invalid_server_token | 401 | Server 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
| Code | Status | Meaning | Fix |
|---|---|---|---|
agent_not_configured | 409 | The agent has no provider key or model. | Add a provider key and pick a model in the console. |
session_not_found | 404 | No such session for this agent, user and tenant. | Start a new session. |
turn_not_found | 404 | No such turn in this session, or one that is not waiting for results. | Use the turnId from turn.awaiting_tools. |
turn_in_progress | 409 | The session already has a running turn. | Wait for turn.done, or cancel the turn. |
unknown_call_id | 409 | A result for a call id the turn did not make. | Use the ids from turn.awaiting_tools. |
call_already_answered | 409 | A result for a call id that already has one, including server calls. | Answer each app call once. |
source_not_found | 404 | The 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_conflict | 409 | An Idempotency-Key was already used for a different signal. | Use a new key for different content. |
Knowledge errors
| Code | Status | Meaning | Fix |
|---|---|---|---|
knowledge_base_not_found | 404 | The knowledge base does not exist or is not in the agent's organization. | Copy the id from the console. |
tenant_uploads_disabled | 403 | The agent's knowledge.tenantUploads setting is off. | Turn it on in the agent's Knowledge page. |
knowledge_quota_exceeded | 413 | The tenant reached 200 files or 200 MB. | Delete files or ask for more room. |
Eval API errors
| Code | Status | Meaning | Fix |
|---|---|---|---|
eval_not_found | 404 | The suite, target version or run does not exist for this agent. | Check the suite name and target. |
eval_run_in_progress | 409 | A run is already queued or running for this agent. | Poll the active run, then start yours. |
eval_limit_reached | 429 | A run is over 500 attempts, or the agent started 30 runs in the last hour. | Reduce cases or repeats, or wait. |
cost_confirmation_required | 400 | confirmCost was not true. The body also carries estimate. Nothing started. | Resend with confirmCost: true. |
Limit errors
| Code | Status | Meaning | Fix |
|---|---|---|---|
rate_limited | 429 | Over a rate limit. | Wait retryAfter seconds. |
limit_reached | 429 | A 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.
| Code | Status | Meaning | Fix |
|---|---|---|---|
provider_key_missing | 502 | The agent's provider key was deleted. | Add a key in the console. |
provider_key_invalid | 502 | The provider rejected the key. | Replace the key. |
provider_out_of_credit | 502 | The provider says the key has no credit. | Add credit with the provider. |
provider_rate_limited | 502 | The provider rate limited the key. retryAfter when known. | Wait and retry. |
provider_model_unavailable | 502 | The key cannot use the agent's model (unknown, retired or not allowed). | Choose another model. |
provider_context_too_long | 413 | The conversation is longer than the model accepts. | Start a new session. |
provider_error | 502 | Any other provider failure, including timeouts. Retried once before any output. | Retry later. |
internal_error | 500 | A 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.