Errors
Copy page
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 body; branch on its code, which never changes.
Content-Type: application/problem+jsonThe problem bodyLink to this section
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 codeLink to this section
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.
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 listLink to this section
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, and each operation's reference section names the HTTP statuses it can return.
On Kelly WireLink to this section
Wire reports errors as an error message on the socket, with its own fields; see control messages. A connection that must end closes with a code from the close-code ranges in the protocol.