Skip to main content

​
Error Response Format

All errors follow a consistent envelope format: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {}
  }
}
FieldTypeDescription
codestringMachine-readable error code. Use this for programmatic handling.
messagestringHuman-readable description of the error.
detailsobjectOptional. Field-level validation errors (present on VALIDATION_INVALID_BODY).

​
Error Codes

CodeDescription
VALIDATION_INVALID_BODYThe request body failed schema validation. Check the details field for specific field errors.
VALIDATION_INVALID_JSONThe request body is not valid JSON.
CHAT_RETRY_NO_USER_MESSAGEThe retry target message has no preceding user message to re-send.
AUTH_MISSING_API_KEYNo Authorization header was provided.
AUTH_INVALID_API_KEYThe API key is not valid.
AUTH_EXPIRED_API_KEYThe API key has expired. Generate a new one from the dashboard.
CHAT_CREDITS_EXHAUSTEDThe workspace’s message credit balance is zero. Upgrade the plan or wait for credits to reset.
CHAT_AGENT_CREDITS_EXHAUSTEDThe specific agent’s credit allocation has been used up.
SUBSCRIPTION_PLAN_REQUIREDYour current plan does not include API access. A Standard Plan or above is required.
AUTH_INSUFFICIENT_PERMISSIONSThe API key does not have the required permissions for this operation.
CHAT_MODEL_NOT_ALLOWEDThe agent is configured to use a model that is not available on the current plan.
CHAT_CONVERSATION_MISMATCHThe conversation does not belong to the specified agent.
CHAT_CONVERSATION_NOT_ONGOINGThe conversation has ended or been taken over and cannot receive new messages.
AGENT_NOT_FOUNDNo agent matches the provided ID, or it does not belong to the authenticated workspace.
RESOURCE_NOT_FOUNDThe requested resource does not exist.
RESOURCE_MESSAGE_NOT_FOUNDThe specified message was not found in the conversation.
RESOURCE_MESSAGE_NOT_ASSISTANTOnly assistant messages support feedback and metadata updates.
CHAT_RETRY_MESSAGE_NOT_FOUNDThe message ID provided for retry was not found in the conversation.
RATE_LIMIT_TOO_MANY_REQUESTSRate limit exceeded. Check the Retry-After header for how long to wait. See Authentication for details.
INTERNAL_SERVER_ERRORAn unexpected error occurred. If this persists, contact support with the x-request-id header value.
CHAT_STREAMING_ERRORAn 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})`);
  }
}