Error Codes

When a request fails with a code the library knows, Chat UI shows a friendly message in the person's language instead of the server's English text. This page lists every code that has a message (English and Turkish are built in), what the page does about it, and how to change the wording.

New in 0.4.0

Localized messages for server error codes, recovery from conflicts, and error.serverMessage.

How an error reaches the UI

A failed request becomes an Error with status, code and, when the server sent them, details (see Server routes). Chat and useChat then:

1. look up chat.error.code.<code> (the code lower-cased, so PENDING_ACTION and pending_action are the same);
2. if there is a string, replace the error's message with it and keep the server's own wording on error.serverMessage (the original error is error.cause; code, status and details stay);
3. otherwise leave the message as the server wrote it.

A few strings contain {detail}, which is replaced with the server's message (validation_error, invalid_request, invalid_approved_args, guardrail_blocked, file_too_large, unsupported_file_type, invalid_budget). The error reaches onError, useChat().error and the error banner already localized.

<Chat
  onError={(error) => {
    const { code, status, serverMessage } = error as Error & { code?: string; status?: number; serverMessage?: string };
    report({ code, status, serverMessage, shown: error.message });
  }}
/>

localizeError(error, t, has) and normalizeErrorCode(code) are exported for your own components.

What the page does about a code

Code	Reaction
action_pending, pending_action, conversation_busy, budget_reached	The conversation on screen is stale (a card, a running turn or a used-up limit it did not know about): it is fetched again so the card, the latest answer, the follow or the usage notice shows, and the typed text stays in the composer
action_expired, action_cancelled, action_not_pending	The card turns Expired, Cancelled or Answered and the composer is released
Any other error on answering a card	The card goes back to waiting
upload_failed	A network failure during an upload (the request never got an answer), raised by the client itself
stream.error events	The event's code is passed on, so a failure in the middle of a stream is localized too

Statuses the sources name: conversation_busy and action_pending are 409, budget_reached is 402, budget_forbidden is 403, invalid_budget is 400, action_disabled is 403, export_format_unsupported is 501 (answered to a pdf export; the chat repeats the request as the print view).

Codes

Requests and permissions

Code	Message shown (English)
validation_error	The request was not accepted.
invalid_request	The request was not accepted.
not_found	That conversation or item was not found. It may have been removed.
forbidden	You do not have permission to do that.
authentication_error	Your session has expired. Sign in again to continue.
authorization_error	You do not have permission to do that.
authorization_unavailable	Permissions could not be checked right now. Try again in a moment.
internal_error	Something went wrong on the server. Try again in a moment.
not_supported	This is not supported here.
cancelled	The request was cancelled.
identity_required	Sign in to see your conversations.
unsupported_media_type	The file could not be sent that way. Attach it again.
invalid_host_result	The assistant gave an answer that could not be used. Try again.
licence_required	This feature needs a license.
payload_too_large	The file is larger than the server accepts.

Agents and portals

Code	Message shown (English)
agent_unavailable	This assistant is not available right now. Try again later.
agent_access_denied	You do not have access to this assistant.
portal_not_found	This portal could not be found.
portal_disabled	This portal is turned off.
portal_access_denied	You do not have access to this portal.

Conversations and runs

Code	Message shown (English)
conversation_busy	The assistant is still working on this conversation. Wait for it to finish, then try again.
conversation_conflict	The conversation changed while that was happening. Try again.
lease_lost	Another server took this conversation over. Try again.
run_interrupted	The assistant was interrupted. Send your message again.
nothing_to_continue	There is nothing to continue.
task_busy	This task is still running.
task_finished	This task has already finished.

Approvals, questions and host tools

Code	Message shown (English)
action_not_pending	That request was already answered.
action_expired	That request has expired.
action_cancelled	That request was cancelled.
action_pending	The assistant is waiting for your answer above. Answer it to continue.
pending_action	The assistant is waiting for your answer above. Answer it to continue.
action_forbidden	Only the person who started this chat can answer this request.
action_not_resumable	This request can no longer be continued. Send a new message instead.
action_disabled	This action is turned off for this assistant.
invalid_approved_args	The edited arguments were not accepted.
invalid_client_tool_result	The result of the tool that ran in your browser was not accepted. It may be too large to send back.

Usage limits and quotas

Code	Message shown (English)
budget_reached	This conversation reached its usage limit.
budget_forbidden	You can not change the usage limit of this conversation.
invalid_budget	That usage limit is not accepted.
budget_unavailable	Usage limits are not available for this assistant.
budget_misconfigured	Usage limits are not set up correctly for this assistant.
rate_limited	Too many requests. Wait a moment and try again.
quota_exceeded	The usage quota was reached. Try again later or contact the administrator.
too_many_conversations	There are too many open conversations. Delete an old one first.
message_too_long	The message is too long. Shorten it and try again.
guardrail_blocked	Your message was blocked by a content policy.

Files

Code	Message shown (English)
file_quota_exceeded	The file storage limit was reached.
too_many_files	There are too many files in this conversation.
file_too_large	A file is larger than this assistant accepts.
unsupported_file_type	This type of file is not accepted.
files_not_supported	This assistant does not accept files.
attachments_disabled	Files are not set up for this assistant.
attachment_not_found	An attached file could not be found. Attach it again.
upload_failed	The file could not be uploaded. Try again.
storage_unavailable	File storage is not available for this assistant right now.
storage_not_configured	File storage is not available for this assistant right now.
storage_limit_exceeded	The storage is full, so the file could not be kept.

Message actions, history and export

Code	Message shown (English)
not_latest_message	Only the newest answer can be generated again.
message_not_found	That message was not found. It may have been removed.
message_not_editable	Only your own messages can be edited.
invalid_rating	That rating was not accepted.
feedback_disabled	Feedback is turned off here.
invalid_feedback	Your feedback was not accepted. Check the rating and the comment, then try again.
invalid_message_target	That message can't be used for this. Reload the conversation and try again.
export_disabled	Exporting conversations is turned off here.
export_format_unsupported	That download format is not available here. Choose another one.
too_many_ids	Too many conversations were selected at once.

Terms of use

Code	Message shown (English)
terms_required	Accept the terms of use to continue.
terms_changed	The terms have changed. Reload the page to read the new version.
invalid_version	The version of the terms is missing or not valid. Reload the page and try again.

Codes outside this list show the server's message unchanged.

Change the wording

Every string is a message like any other and can be replaced with customMessages:

<Chat
  customMessages={{
    en: { "chat.error.code.rate_limited": "Slow down a little, please." },
    tr: { "chat.error.code.rate_limited": "Biraz yavaşlayın, lütfen." },
  }}
/>

A locale other than en and tr falls back to English per key. See Internationalization.

Embedded chat sign-in codes

The sign-in of an embedded chat has its own codes, on the auth:error event (the server's code, lower-cased) and on the "Sign-in failed" screen:

Code	Meaning
identity_not_found	The person is not set up for this chat. The screen says to ask an administrator for access
token_expired and other server codes	Whatever the server answered to the exchange; the screen shows a generic message and the reference
network_error	The server could not be reached
invalid_response	The server's answer to the exchange was not understood
auth_failed, forbidden, rate_limited, exchange_failed	Fallbacks for a 401, 403, 429 and any other refusal that came without a code
session_expired	The session ended without a renewal

See Embedding the Chat.

Related

• Approvals and Questions
• Server routes
• Debugging