API: Errors, Status Codes & Limits

Complete reference of HTTP status codes, the OpenAI-compatible error shape, and the budget and size limits of the public Kasimir API.

The public Kasimir API is OpenAI-compatible: errors are returned in the same JSON shape as OpenAI, so off-the-shelf OpenAI SDKs surface them as a normal exception or error object. This chapter describes exactly which status codes the /api/v1/* endpoints throw, what they mean, how the error object is structured, and which hard limits (budget, payload sizes) apply — all derived directly from the source code.

Error shape

Every error from the OpenAI-compatible endpoints (POST /v1/chat/completions, POST /v1/embeddings, GET /v1/models) is translated into the OpenAI schema by server/utils/apiError.ts (toOpenaiError):

{
  "error": {
    "message": "Model \"foo\" not found",
    "type": "not_found_error",
    "code": null
  }
}

The type value is mapped strictly from the status code:

Status codes in detail

The following table lists every status code thrown by the /api/v1/* surface, with the triggering code location and its meaning.

401 – Authentication

authenticateApiKey (server/utils/apiKeyAuth.ts) throws 401 in three cases:

• No bearer token — message: "Missing bearer token"

• Invalid key — hash not found in company_api_keys — message: "Invalid API key"

• Revoked key — revoked_at is set — message: "API key revoked"

Keys have the format kasi_<32 chars> and are stored only as a SHA-256 hash; the plaintext is shown once at creation.

402 – Budget

assertCompanyBudget (server/utils/apiUsage.ts) checks before forwarding to the upstream:

• companies.monthly_budget_eur is null or ≤ 0 → unlimited, no cap.

• Otherwise the monthly spend is fetched via company_month_spend_eur. If used ≥ budget, a 402 is returned, e.g. Monthly budget of €100.00 reached (used €100.42).

403 – Permission

Two independent causes:

• Missing scope — authenticateApiKey(event, ['chat:write']) throws Missing scope: chat:write if the key lacks the required scope. GET /v1/models requires no special scope; chat/completions and embeddings require chat:write.

• Non-EU gate — resolveApiModel throws 403 when the model has eu_hosted = false and companies.allow_non_eu_models is not true: Model "…" is not enabled for your organization (non-EU model).

404 – Not found

resolveApiModel (chat/embeddings) and the assistant handler throw 404 when:

• the slug does not exist in models, is inactive, or has a different purpose (chat vs embedding),

• the slug is listed in companies.disabled_model_slugs (deliberately masked as "not found"),

• an assistant (/v1/assistants/{id}/run) does not exist or belongs to a foreign company (tenant isolation),

• the assistant's model does not exist/is inactive — Model "…" not found or inactive.

502 / passed-through 5xx – Upstream

If the LiteLLM layer does not respond with 2xx (or the body is missing for streaming), Kasimir throws res.status || 502 with Upstream error: <first 200 chars of the upstream response>. A 502 typically means the upstream returned no usable status at all.

Limits

In Phase 1 there are no rate limits and no 429 responses — per-key spend caps and per-key rate limits are explicitly deferred to Phase 2. The only enforced "quantity" limit is the company monthly budget (see 402). Beyond that, payload schema bounds apply:

Handling errors (recommendations)

Because the error shape is OpenAI-conformant, every OpenAI SDK catches these cases automatically — e.g. the Python SDK raises AuthenticationError (401), PermissionDeniedError (403), NotFoundError (404) and APIStatusError (5xx). Read error.message for the specific reason.