API documentation

Errors

The error format and every error code the API returns.

Last updated October 2, 2026

Every KleioBase API error is a JSON body with the same shape, an error object holding code, message, request_id and sometimes details:

{
  "error": {
    "code": "validation_failed",
    "message": "limit must be between 1 and 100",
    "request_id": "req_...",
    "details": {}
  }
}

code is stable and meant for your code to branch on.
message is for people. Do not parse it.
request_id also arrives in the Request-Id response header. Quote it if you contact support.
details is present only for some errors, such as the Zod issues behind a 422.

The set of codes is open: new codes can be added without a new API version, so treat an unknown code like its status class. See Versioning.

Codes

Code	Status	When it happens
`unauthorized`	401	The API key is missing, malformed, unknown or revoked.
`forbidden`	403	The account has no paid plan, a read key was used for a write, or a plan limit (such as the number of people) was reached.
`not_found`	404	The workspace or resource does not exist, is in Trash, or is not yours.
`validation_failed`	422	The request is invalid. `details` explains which fields.
`conflict`	409	The request clashes with the current state: an archived workspace, a record in the wrong status, an Idempotency-Key reused with a different request, and similar.
`insufficient_credits`	402	Not enough credits to process a record. `details` has `used`, `limit`, `credits_remaining` and `shortfall`.
`rate_limited`	429	Too many requests. Wait the number of seconds in the `Retry-After` header. See Rate limits.
`internal_error`	500	Something went wrong on our side. Retry later and quote the `request_id` if it persists.

Headers on every response

API-Version is the major version, currently 1.
Request-Id identifies this request.
Retry-After is added to a 429.

Retrying safely

Retry 429 after the wait, and 500 with backoff. Do not blindly retry a 422 or 409: fix the request, or wait until the state it clashed with has changed. For writes, send an Idempotency-Key so a retry cannot apply the change twice. See Idempotency.

Building a product on KleioBase? Contact us.