Skip to Content
Baseera Docs

Error handling

How the server helpers report failures, which codes to retry, and what never throws.

The server helpers that call the runtime do not throw. They return a result: { ok: true, ... } or { ok: false, code }. Check ok, then switch on code. Nothing here logs a key or a token.

What throws and what does not

FunctionOn failure
signUserTokenThrows TypeError or RangeError before it signs. See Signing user tokens.
signTenantUploadTokenThrows on a missing field.
verifyWebhookNever throws. Returns { ok: false, reason }.
verifyFinishNever throws. Fails closed.
purgeTenantKnowledgeNever throws.
createBaseera().kb.*Never throws.
createBaseera().signalNever throws.

Codes and what to do

CodeMeaningWhat to do
invalid_server_tokenThe key is wrong or revoked, or the token was refused.Check BASEERA_SECRET_KEY and BASEERA_AGENT_ID. Do not retry.
invalid_requestThe request broke a rule: a field, a limit, a bad id.Fix the input. Do not retry.
knowledge_base_not_foundThe knowledge base does not exist or is not the agent's organization's.Check BASEERA_KNOWLEDGE_BASE_ID.
message_too_largeThe request was too big.Send long text as a file.
rate_limitedYou hit a limit. retryAfter is in seconds.Wait retryAfter seconds, then retry.
idempotency_conflictThe same idempotency key with different content.Use a new key for different content.
unavailableA network error, timeout, redirect, non-HTTPS URL or server error.Retry later with backoff.
not_foundkb.status: the knowledge base exists but the item does not.Push the item first.

verifyFinish has its own codes: receipt_not_found, entity_mismatch, receipt_expired, receipt_used, override_required and unavailable. Treat unavailable as a refusal and let the person retry.

verifyWebhook returns a reason: missing_header, malformed_header, bad_secret, timestamp_outside_tolerance, signature_mismatch or invalid_body. Answer 400 for any of them.

Retry rules

Retry only unavailable and rate_limited. Everything else is a bug in the call or in your configuration, and the same request will fail again.

async function pushWithRetry(input: KbUpsertInput, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    const result = await baseera.kb.upsert(input);
    if (result.ok) return result;
    if (result.code === "rate_limited") {
      await sleep((result.retryAfter ?? 1) * 1000);
    } else if (result.code === "unavailable") {
      await sleep(2 ** i * 500);
    } else {
      throw new Error(`Baseera refused the push: ${result.code}`);
    }
  }
  throw new Error("Baseera is unavailable");
}

Pushing the same externalId again is safe: it replaces the item, and unchanged content is not embedded again. purgeTenantKnowledge twice is harmless. signal retries are safe with an idempotency key.

Timeouts

CallTimeout
verifyFinish (VERIFY_FINISH_TIMEOUT_MS)5 seconds
purgeTenantKnowledge (PURGE_TENANT_TIMEOUT_MS)30 seconds
Knowledge calls (KB_REQUEST_TIMEOUT_MS)30 seconds
File uploads (KB_UPLOAD_TIMEOUT_MS)120 seconds

Log without leaking

Do not log a result that might hold a key, and never log the Authorization-like headers. Pass errors through redactForLog from @baseera/core. See Logging safely.

Next steps

On this page