# Errors

How Kelly reports a failed call, the fields every error body carries and how to branch on them.

A failed call answers with a real HTTP status and an RFC 9457 [problem details](/glossary#problem-details) body; branch on its `code`, which never changes.

```http Response headers
Content-Type: application/problem+json
```

## The problem body

Every error body has these fields. `code` is stable snake_case; `detail` is prose for developers and may be reworded, so never parse it.

| Field | Type | Meaning |
| --- | --- | --- |
| `type` | string, always present | The error's documentation URI. |
| `title` | string, always present | A short, fixed summary of the code. |
| `status` | integer, always present | The HTTP status. |
| `code` | string, always present | Stable snake_case code from the error catalogue. |
| `detail` | string, nullable | What went wrong this time, for developers. |
| `param` | string, nullable | The parameter, field or header at fault. |
| `doc_url` | string, always present | Cause and fix for this code. |
| `request_id` | string, nullable | The Request-Id of the failed request. |
| `retryable` | boolean, always present | Whether retrying the same request can succeed. |
| `display_message` | string | Plain wording an app may show its end user (API-ERR-3); it never carries developer detail. |
| `instance` | string | A URI for this occurrence, when there is one. |

## Branching on the code

Read `code` first, then `retryable`. A code you don't know yet is not a reason to fail hard: fall back on the HTTP status, and treat the call as not retryable unless `retryable` is true.

```ts client.ts
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.KELLY_API_KEY}` } });
if (!res.ok) {
  const problem = await res.json();
  if (problem.retryable) return retryLater(problem);
  throw new Error(`${problem.code}: ${problem.detail ?? problem.title} (request ${problem.request_id})`);
}
```

## The code list

One page per code, with what it means, how to fix it and whether to retry, comes with the error catalogue's export (planned, P8, October 16, 2026). Until then the codes are listed in the [API definition](/reference#basics), and each operation's reference section names the HTTP statuses it can return.

## On Kelly Wire

Wire reports errors as an `error` message on the socket, with its own fields; see [control messages](/reference/wire#control-messages). A connection that must end closes with a code from the close-code ranges in the [protocol](/reference/wire#protocol).

---

Last updated October 16, 2026

Support: support@askkelly.ai · Security and disclosure: https://docs.askkelly.ai/security

Information is the edge. Odds are information, not advice · 21+ · Get help