Errors
The CLI prints failures as error: … on stderr and exits with status 1. Over HTTP, bodies are usually:
{
"title": "...",
"detail": "..."
}
Auth, IP rate limiting, and some file routes (ingest, content) use:
{
"error": "invalid api key"
}
Other auth examples: {"error":"missing or invalid authorization bearer token"}, {"error":"rate limit exceeded"}.
Status codes
| Status | Meaning |
|---|---|
400 |
Bad input: missing fields, invalid path, bad search params, malformed JSON |
401 |
Missing or invalid API key |
403 |
Operation not allowed under your plan (for example knowledgebase count or storage) |
404 |
Unknown knowledgebase id for your key, or missing file/path |
409 |
Index not searchable yet (see Index and search) |
413 |
Upload body larger than your plan’s per-file upload size |
429 |
Rate limited (requests, uploads/day, downloads/day, sync accepted too often, or IP limit) |
502 |
Temporary upstream failure; retry later |
Knowledgebase ids that do not exist or belong to another account both surface as 404. Do not treat 404 as proof that an id is unused globally.
Rate-limit response headers
Authenticated responses may include:
| Header | Meaning |
|---|---|
X-RateLimit-Limit |
Request ceiling for the active window |
X-RateLimit-Remaining |
Requests left in that window |
X-RateLimit-Reset |
Unix time when the window resets |
Retry-After |
Seconds to wait (typically on 429) |
When you see 429, back off using Retry-After if present, then retry. Sync also rejects more than one accepted call per knowledgebase per second.
Separately, each client IP is limited to 300 requests per minute. Exceeding that returns 429 with Retry-After and {"error":"rate limit exceeded"}.
Common CLI failures
| Symptom | Likely cause |
|---|---|
api key required: set -api-key or KOBOLD_API_KEY |
Env/flag not set |
401 / invalid api key |
Wrong or revoked key |
404 on -kb / -id |
Typo, deleted KB, or id from another account |
409 on search |
Index still pending / empty; sync and wait |
413 on ingest |
File larger than per-file upload size from stats get |
400 on mode=full without valid byte length |
Use -byte-length in 1–1024 (CLI defaults to 512 when omitted) |
Checking your ceilings
kobold-cli stats get
Inspect limits for plan ceilings (storage, knowledgebase count, upload size, daily uploads/downloads, request rates, and related fields) and usage for current counters. This wiki does not document how those counters are maintained—only that stats is how you read them.