OpenMax
Free Trial

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 TypeError is thrown, with no kind.
  • An upload PUT that fails, loses the network or is cancelled: a plain Error. The prepare and finalize requests around the upload still fail with ChatSdkRequestError.
  • An upload outside a conversation scope (no conversation id): a plain Error.

For these, isChatSdkError() returns false.