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
| Function | On failure |
|---|---|
signUserToken | Throws TypeError or RangeError before it signs. See Signing user tokens. |
signTenantUploadToken | Throws on a missing field. |
verifyWebhook | Never throws. Returns { ok: false, reason }. |
verifyFinish | Never throws. Fails closed. |
purgeTenantKnowledge | Never throws. |
createBaseera().kb.* | Never throws. |
createBaseera().signal | Never throws. |
Codes and what to do
| Code | Meaning | What to do |
|---|---|---|
invalid_server_token | The key is wrong or revoked, or the token was refused. | Check BASEERA_SECRET_KEY and BASEERA_AGENT_ID. Do not retry. |
invalid_request | The request broke a rule: a field, a limit, a bad id. | Fix the input. Do not retry. |
knowledge_base_not_found | The knowledge base does not exist or is not the agent's organization's. | Check BASEERA_KNOWLEDGE_BASE_ID. |
message_too_large | The request was too big. | Send long text as a file. |
rate_limited | You hit a limit. retryAfter is in seconds. | Wait retryAfter seconds, then retry. |
idempotency_conflict | The same idempotency key with different content. | Use a new key for different content. |
unavailable | A network error, timeout, redirect, non-HTTPS URL or server error. | Retry later with backoff. |
not_found | kb.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
| Call | Timeout |
|---|---|
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.