Errors and limits

Status codes, the error envelope, rate limits and how to retry safely.

Every klerc API response has a status code and a JSON envelope. This page covers what the codes mean, how errors are shaped, and the limits to design for.

Status codes#

Code	Meaning	What to do
`200`	OK — the request succeeded	Read `data`
`201`	Created — something new was made	Read `data` for the new resource
`401`	Authentication failed — the token is missing, malformed, revoked or unknown	Check the `Authorization` header and the token
`403`	Insufficient scope, or the feature is switched off for the organisation	Add the scope the operation needs, or ask an admin to enable the feature
`404`	Not found — or not visible to the token's owner	Check the id, and whether the owner can see the record

A 404 can mean a record exists but you're not allowed to see it. klerc doesn't reveal the difference, on purpose.

The error envelope#

Errors share one shape:

json

{  "status": 403,  "error": {    "code": "…",    "message": "…"  },  "message": "…"}

Branch on the HTTP status and error.code; show error.message to people. The reference doesn't publish a list of error codes, so log unfamiliar ones and treat them by their HTTP status.

Rate limits#

Surface	Limit
Authentication	20 requests per 15 minutes
API	600 requests per minute per IP address

If you go over, requests are rejected until the window resets. Spread large jobs out, prefer bulk endpoints to loops (see Working with records), and use limit to fetch fewer, larger pages.

Retrying safely#

Reads are safe to retry. Back off exponentially — 1s, 2s, 4s — with a little random jitter.
Writes — operations the reference marks as mutating — aren't automatically safe. If a create timed out, look the record up before trying again, or you may make it twice.
Don't retry 401 or 403. They won't succeed until the token, scopes or feature settings change.

Pagination limits#

List endpoints accept limit and return a cursor when there's more. Keep paging until no cursor comes back, and don't assume a page is full. The reference doesn't document a maximum page size, so use modest values — 50 to 100 — and let the cursor do the work.