Error Handling - Chatbase

Error Response Format

All errors follow a consistent envelope format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}

Field	Type	Description
`code`	`string`	Machine-readable error code. Use this for programmatic handling.
`message`	`string`	Human-readable description of the error.
`details`	`object`	Optional. Field-level validation errors (present on `VALIDATION_INVALID_BODY`).

Error Codes

Code	Description
`VALIDATION_INVALID_BODY`	The request body failed schema validation. Check the `details` field for specific field errors.
`VALIDATION_INVALID_JSON`	The request body is not valid JSON.
`CHAT_RETRY_NO_USER_MESSAGE`	The retry target message has no preceding user message to re-send.
`AUTH_MISSING_API_KEY`	No `Authorization` header was provided.
`AUTH_INVALID_API_KEY`	The API key is not valid.
`AUTH_EXPIRED_API_KEY`	The API key has expired. Generate a new one from the dashboard.
`CHAT_CREDITS_EXHAUSTED`	The workspace’s message credit balance is zero. Upgrade the plan or wait for credits to reset.
`CHAT_AGENT_CREDITS_EXHAUSTED`	The specific agent’s credit allocation has been used up.
`SUBSCRIPTION_API_RESTRICTED_PLAN`	Your current plan does not include API access. A Standard Plan or above is required.
`AUTH_INSUFFICIENT_PERMISSIONS`	The API key does not have the required permissions for this operation.
`CHAT_MODEL_NOT_ALLOWED`	The agent is configured to use a model that is not available on the current plan.
`CHAT_CONVERSATION_MISMATCH`	The conversation does not belong to the specified agent.
`CHAT_CONVERSATION_NOT_ONGOING`	The conversation has ended or been taken over and cannot receive new messages.
`RESOURCE_NOT_FOUND`	The requested resource does not exist.
`RESOURCE_TOOL_CALL_NOT_FOUND`	No pending client action matches the provided `toolCallId`. It may have expired or already been resolved.
`RESOURCE_MESSAGE_NOT_FOUND`	The specified message was not found in the conversation.
`RESOURCE_MESSAGE_NOT_ASSISTANT`	Only assistant messages support feedback and metadata updates.
`CHAT_RETRY_MESSAGE_NOT_FOUND`	The message ID provided for retry was not found in the conversation.
`RATE_LIMIT_TOO_MANY_REQUESTS`	Rate limit exceeded. Check the `Retry-After` header for how long to wait. See Authentication for details.
`INTERNAL_SERVER_ERROR`	An unexpected error occurred. If this persists, contact support with the `x-request-id` header value.
`CHAT_STREAMING_ERROR`	An error occurred during stream generation. The stream may have been partially delivered.
`SOURCE_NOT_FOUND`	Source doesn’t exist, belongs to a different agent, or has been permanently deleted.
`SOURCE_TYPE_NOT_SUPPORTED`	Attempting to update a `notionPage` via PUT. Manage Notion sources through the dashboard integration.
`SOURCE_PENDING_DELETION`	Source has `toBeDeleted` status. Restore it before making edits.
`SOURCE_NOT_RESTORABLE`	Restore was called on a source that is not in `toBeDeleted` state.
`SOURCE_LINK_LIMIT_EXCEEDED`	The 15 crawl/sitemap-parent limit per agent has been reached on create or restore.
`SOURCE_SIZE_LIMIT_EXCEEDED`	Creating or updating this source would exceed the plan’s storage limit.
`SOURCE_DUPLICATE`	A link source with this URL and `linkType` already exists for this agent.
`SOURCE_URL_IMMUTABLE`	A link’s URL cannot be changed via PUT. Delete and recreate the source to use a different URL.

Example with field-level details (VALIDATION_INVALID_BODY):

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request",
    "details": {
      "message": "Required"
    }
  }
}

Handling Errors

const response = await fetch(
  "https://www.chatbase.co/api/v2/agents/YOUR_AGENT_ID/chat",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ message: "Hello" }),
  }
);

if (!response.ok) {
  const { error } = await response.json();
  const requestId = response.headers.get("x-request-id");

  switch (error.code) {
    case "RATE_LIMIT_TOO_MANY_REQUESTS":
      const retryAfter = response.headers.get("Retry-After");
      // Wait and retry
      break;
    case "CHAT_CREDITS_EXHAUSTED":
      // Notify user about credit limit
      break;
    case "VALIDATION_INVALID_BODY":
      // Fix request based on error.details
      console.log("Validation errors:", error.details);
      break;
    default:
      console.error(`[${error.code}] ${error.message} (request: ${requestId})`);
  }
}