Errors
ChatSdkRequestError: how OpenMax HTTP statuses map to ChatSdkError kinds, and how a 401 is renewed.
Errors
What the OpenMax adapter throws when it fails, and where the kind comes from. What each error kind means, how the UI handles it and when onUnauthorized is called are on @openmaxai/chat-sdk · Errors; this page covers only the OpenMax side of the mapping.
ChatSdkRequestError
class ChatSdkRequestError extends ChatSdkError {
readonly status: number;
readonly field?: string;
constructor(status: number, message: string, code?: string, options: {
kind?: ChatSdkErrorKind;
cause?: unknown;
field?: string;
} = {});
}
A failed REST request. It is a subclass of ChatSdkError, so isChatSdkError() recognises it and components and your code can branch on kind.
| Field | Description |
|---|---|
status |
The HTTP status; 0 means no complete response (offline, blocked cross-origin, the request was aborted or timed out, or getting the token failed; also when one of these happens after the headers arrived but before the body was fully read) |
message |
One sentence for the user, shown as is: when the code in the backend's error body is known, the sentence for it from the SDK's error-code table (language per locale); an empty string for an unknown code, no code (including no response and token failures), or a sentence that needs values the backend did not send, and components then use their own copy for the kind. When creating a group (POST /api/v1/conversations/groups) fails with 403 AUTH_ORG_MEMBERSHIP_REQUIRED it is a neutral sentence instead ("Some members are no longer in the organization, or you don't have permission."): the backend returns the same code when a selected member id is invalid (soft-deleted, such as a torn-down platform agent; from another organization; or nonexistent) as when you yourself are no longer in the organization; other requests keep the table's sentence for that code. The backend's detail / title text never goes here |
code |
The stable code from the backend's error body, when there is one; "token_unavailable" when getting the token failed |
kind |
Derived from the status, see the table below; the fourth constructor argument can set another kind |
cause |
The original error, when there is one. When the backend sent an error body, it is that body (with the detail / title text); with no response, it is whatever fetch or getToken threw |
field |
The field path in the backend error body (e.g. a form card's answers.<key>.text), when there is one |
Both backend error shapes are understood: the nested { error: { … } } and the top-level { detail, title, code }.
Status to kind
| Case | kind |
|---|---|
401 |
unauthorized (after one token renewal and one re-send, see Renewal) |
403 |
forbidden |
404, 410 |
not_found |
409 |
conflict |
400, 413, 422 |
validation |
429 |
rate_limited |
408 |
timeout |
502, 503, 504 |
unavailable |
Any other 5xx |
server |
status 0: offline, DNS, blocked cross-origin (fetch throws TypeError) |
network |
status 0: request aborted through its signal (AbortError, or any reason the caller gave, such as abort("navigated"); same before the headers and while reading the body) |
cancelled |
status 0: AbortSignal.timeout() ran out (TimeoutError) |
timeout |
Getting the token failed (code "token_unavailable") |
Follows what getToken threw, see OpenMaxGetTokenOptions |
Recall, edit or reaction refused with 412 or 403 |
forbidden (isChatOperationNotAllowed() recognises it, and the UI says it cannot recall / cannot edit) |
| Any status not in this table | unknown |
Renewal
On 401 the adapter calls getToken({ refresh: true }) (this is the moment to really renew, not to hand back the cached token) and re-sends that request once with the new token; only when no token comes back, or the re-sent request gets 401 again, does it fail with unauthorized. Several requests refused at the same time (or one after another) share one renewal. The realtime ticket exchange takes the same path: after a successful renewal it exchanges a ticket again and connects as usual.
When getToken returned OpenMaxToken ({ token, expiresAt }), the token is renewed before it expires, and only a 401 whose code is AUTH_TOKEN_EXPIRED renews and re-sends; any other 401 (a revoked token or key) fails with unauthorized at once.
A renewal that failed because of the network (getToken threw a ChatSdkError with kind network) is not a credential failure: that call fails with network, onUnauthorized is not called, realtime backs off and reconnects as usual, and the next 401 renews again.
When the credentials are gone: the failing call throws a ChatSdkRequestError with kind unauthorized, and realtime stops reconnecting and reports once through sink.error; with the { adapter } form, onUnauthorized is called if given, and with the one-line form (which does not take onUnauthorized) the SDK shows "session expired" once through attention.notify. See @openmaxai/chat-sdk · Expired credentials. A realtime connection closed by the server with the credentials-invalid close code is handled the same way, once.
When the ticket request is refused (403, kind forbidden), realtime also stops reconnecting and reports once through sink.error, but this is not expired credentials: no renewal, no onUnauthorized, no "session expired" notice. Realtime does not recover on its own: after granting the Key the missing permission, create a new host (or reload the page) to reconnect.
Not a ChatSdkRequestError yet
- A connection drop while the response body is being read (after the headers arrived): the raw
TypeErroris thrown, with nokind. - An upload PUT that fails, loses the network or is cancelled: a plain
Error. The prepare and finalize requests around the upload still fail withChatSdkRequestError. - An upload outside a conversation scope (no conversation id): a plain
Error.
For these, isChatSdkError() returns false.
