Errors

Introduction

react-ai-chat provides a ChatbotError class for representing errors that can occur while processing chatbot requests.

Each ChatbotError contains a human-readable message and a code that identifies the type of error.

`ChatbotError`

Import it from the package:

import { ChatbotError } from "react-ai-chat";

Create an error with a message and optional error code:

const error = new ChatbotError("Something went wrong", "UNKNOWN");

console.log(error.message);
console.log(error.code);

The error extends the standard JavaScript Error class.

const error = new ChatbotError("Request failed", "PROVIDER");

console.log(error instanceof Error); // true
console.log(error instanceof ChatbotError); // true
console.log(error.name); // "ChatbotError"

The error code defaults to "UNKNOWN" when no code is provided:

const error = new ChatbotError("Something went wrong");

console.log(error.code); // "UNKNOWN"

Error codes

ChatbotError supports these codes:

Code	Meaning
`RATE_LIMIT`	A provider has rejected the request because a rate limit was reached
`AUTHENTICATION`	Provider authentication failed
`INVALID_REQUEST`	The request is invalid
`PROVIDER`	An error occurred with the AI provider
`UNKNOWN`	The error does not match another category

The available codes are represented by the ChatbotErrorCode type:

type ChatbotErrorCode =
  | "RATE_LIMIT"
  | "AUTHENTICATION"
  | "INVALID_REQUEST"
  | "PROVIDER"
  | "UNKNOWN";

Handling errors in the Chatbot

The ready-made <Chatbot /> component accepts an onError callback.

import { Chatbot } from "react-ai-chat";

export default function App() {
  return (
    <Chatbot
      onError={(error) => {
        console.error("Chatbot error:", error);
      }}
    />
  );
}

The callback receives an Error:

onError?: (error: Error) => void;

You can use it to display custom error UI or send errors to your application's logging system.

Handling errors with `ChatbotError`

Use instanceof to check whether an error is a ChatbotError:

import { ChatbotError } from "react-ai-chat";

function handleError(error: Error) {
  if (error instanceof ChatbotError) {
    console.error(error.code);
    console.error(error.message);
  }
}

You can then handle each error code separately:

import { ChatbotError } from "react-ai-chat";

function handleError(error: Error) {
  if (!(error instanceof ChatbotError)) {
    console.error(error);
    return;
  }

  switch (error.code) {
    case "RATE_LIMIT":
      console.log("Please try again later.");
      break;

    case "AUTHENTICATION":
      console.log("Check the provider credentials.");
      break;

    case "INVALID_REQUEST":
      console.log("Check the request data.");
      break;

    case "PROVIDER":
      console.log("The AI provider returned an error.");
      break;

    case "UNKNOWN":
      console.log("An unexpected error occurred.");
      break;
  }
}

Creating errors manually

You can create ChatbotError instances in your own application code:

import { ChatbotError } from "react-ai-chat";

throw new ChatbotError("The request was rate limited.", "RATE_LIMIT");

The second argument is optional:

import { ChatbotError } from "react-ai-chat";

throw new ChatbotError("Something went wrong");

When omitted, the code is "UNKNOWN".

`createChatRoute` errors

createChatRoute() can report failures that occur while processing a chat request.

Errors from model generation and route execution are represented using ChatbotError with an appropriate error code.

For example, a provider-related failure can be represented as:

new ChatbotError("The AI provider returned an error.", "PROVIDER");

The error message depends on the failure that occurred.

Your client can handle these errors through the onError callback:

<Chatbot
  onError={(error) => {
    if (error instanceof ChatbotError) {
      console.error(error.code);
      console.error(error.message);
    }
  }}
/>

RAG errors

RAG retrieval has separate error handling.

If RAG retrieval fails, the retrieval error is logged and the chat request can continue without the retrieved context.

The model can then generate a response using the configured system prompt without the failed retrieval result.

This allows retrieval failures to be handled separately from the main chat generation flow.

Custom error handling

You can centralize chatbot error handling in your application:

import { Chatbot, ChatbotError } from "react-ai-chat";

function handleChatbotError(error: Error) {
  if (!(error instanceof ChatbotError)) {
    console.error(error);
    return;
  }

  switch (error.code) {
    case "RATE_LIMIT":
      console.log("Please try again later.");
      return;

    case "AUTHENTICATION":
      console.log("Check the provider credentials.");
      return;

    case "INVALID_REQUEST":
      console.log("Check the request data.");
      return;

    case "PROVIDER":
      console.log("The AI provider returned an error.");
      return;

    case "UNKNOWN":
      console.log("Something went wrong.");
      return;
  }
}

export default function App() {
  return <Chatbot onError={handleChatbotError} />;
}

Server-side errors

Keep provider credentials and server-side error details on the server.

For example:

GOOGLE_GENERATIVE_AI_API_KEY=...
OPENAI_API_KEY=...

Do not expose provider API keys in client-side code.

The client only needs to communicate with your configured chat endpoint.

TypeScript

Both ChatbotError and ChatbotErrorCode can be imported from react-ai-chat:

import { ChatbotError, type ChatbotErrorCode } from "react-ai-chat";

Use ChatbotErrorCode when you need typed error handling:

function getErrorMessage(code: ChatbotErrorCode) {
  switch (code) {
    case "RATE_LIMIT":
      return "Too many requests.";

    case "AUTHENTICATION":
      return "Authentication failed.";

    case "INVALID_REQUEST":
      return "Invalid request.";

    case "PROVIDER":
      return "Provider error.";

    case "UNKNOWN":
      return "Something went wrong.";
  }
}

Error properties

ChatbotError exposes the standard Error properties along with its error code.

Property	Type	Description
`name`	`string`	Always `"ChatbotError"`
`message`	`string`	Description of the error
`code`	`ChatbotErrorCode`	Category of the error

Example:

const error = new ChatbotError("Provider request failed", "PROVIDER");

console.log(error.name);
console.log(error.message);
console.log(error.code);

Chatbot

createChatRoute

RAG

On this page