API Reference
Errors
Every non-2xx response is a JSON body with an HTTP status code you can branch on.
400 Bad Request
The request didn’t pass validation. The body differs slightly depending on where it was caught:
{ "errorCode": "BadRequestBody", "message": "..." }{ "errorCode": "BadRequestParameters", "message": "..." }Both mean the same thing in practice: something structural is wrong — the body isn’t valid JSON, or a required field is missing or the wrong type. Double-check that mention is a string and messages is a non-empty array of { role, content } objects.
{ "message": "..." }A 400 without an errorCode means the request was well-formed but still rejected — for example, if mentiondoesn’t match any agent configured for your team.
401 Unauthorized
Authentication failed before the request reached an agent. The body always includes an errorCode:
| errorCode | Meaning |
|---|---|
NoApiKey | No x-api-key header was sent at all. |
InvalidApiKey | The API key is invalid, expired, or was revoked. |
InvalidTeam | The Klart-Team-Id doesn’t match an authorized team for this key. |
{ "errorCode": "InvalidApiKey" }See Authentication for where to find a valid key and team ID.
500 Internal Server Error
{ "message": "An unexpected error has occurred. Please contact the technical team." }Something went wrong on our side. These are safe to retry with backoff. If it keeps happening, contact us with the approximate time of the request and your team ID (never your API key).
Handling errors
Check the HTTP status code first, then read errorCode when present for the specific reason. All error bodies are JSON, so a single parser handles every case.