Error Handling

Structured error codes and troubleshooting guide for the Chatbase API v2.

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.

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})`);
  }
}