{"slug":"errors","title":"Errors","path":"errors.md","markdown":"# Errors\n\nThe CLI prints failures as `error: …` on stderr and exits with status `1`. Over HTTP, bodies are usually:\n\n```json\n{\n  \"title\": \"...\",\n  \"detail\": \"...\"\n}\n```\n\nAuth, IP rate limiting, and some file routes (ingest, content) use:\n\n```json\n{\n  \"error\": \"invalid api key\"\n}\n```\n\nOther auth examples: `{\"error\":\"missing or invalid authorization bearer token\"}`, `{\"error\":\"rate limit exceeded\"}`.\n\n## Status codes\n\n| Status | Meaning |\n| ------ | ------- |\n| `400` | Bad input: missing fields, invalid path, bad search params, malformed JSON |\n| `401` | Missing or invalid API key |\n| `403` | Operation not allowed under your plan (for example knowledgebase count or storage) |\n| `404` | Unknown knowledgebase id for your key, or missing file/path |\n| `409` | Index not searchable yet (see [Index and search](index-and-search.md)) |\n| `413` | Upload body larger than your plan’s per-file upload size |\n| `429` | Rate limited (requests, uploads/day, downloads/day, sync accepted too often, or IP limit) |\n| `502` | Temporary upstream failure; retry later |\n\nKnowledgebase 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.\n\n## Rate-limit response headers\n\nAuthenticated responses may include:\n\n| Header | Meaning |\n| ------ | ------- |\n| `X-RateLimit-Limit` | Request ceiling for the active window |\n| `X-RateLimit-Remaining` | Requests left in that window |\n| `X-RateLimit-Reset` | Unix time when the window resets |\n| `Retry-After` | Seconds to wait (typically on `429`) |\n\nWhen you see `429`, back off using `Retry-After` if present, then retry. Sync also rejects more than one accepted call per knowledgebase per second.\n\nSeparately, each client IP is limited to **300 requests per minute**. Exceeding that returns `429` with `Retry-After` and `{\"error\":\"rate limit exceeded\"}`.\n\n## Common CLI failures\n\n| Symptom | Likely cause |\n| ------- | ------------ |\n| `api key required: set -api-key or KOBOLD_API_KEY` | Env/flag not set |\n| `401` / invalid api key | Wrong or revoked key |\n| `404` on `-kb` / `-id` | Typo, deleted KB, or id from another account |\n| `409` on search | Index still `pending` / empty; sync and wait |\n| `413` on ingest | File larger than per-file upload size from `stats get` |\n| `400` on `mode=full` without valid byte length | Use `-byte-length` in `1`–`1024` (CLI defaults to `512` when omitted) |\n\n## Checking your ceilings\n\n```bash\nkobold-cli stats get\n```\n\nInspect `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.\n"}