Troubleshooting widget

Common issues and fixes when the widget does not load or behave as expected.

HTTP status codes and errors

When the widget makes requests to our API, you may see these responses. Use them to diagnose issues.

429 Too Many Requests

The request was rate limited. We apply rate limits to keep the platform safe and fair for all users.

Two types of 429:

1. IP-based rate limiting — Applied globally to protect against abuse. If too many requests come from the same IP in a short time, the request is rejected. The response body typically says: "Too many requests. Please try again later." Wait a moment and retry. Limits are per IP (e.g. 20 requests per second, 100 per minute, 1000 per hour).

2. Workspace plan limit exceeded — Your workspace has hit its usage limit for the current period (per minute or per day, based on your plan). The response includes details such as:

   • reason: daily_limit_exceeded or minute_limit_exceeded
   • currentUsagePerMinute, limitPerMinute
   • currentUsagePerDay, limitPerDay
   • resetAtPerMinute, resetAtPerDay — when the limit resets

What to do: Wait until the reset time, or upgrade your plan for higher limits. Check the response details to see which limit was hit and when it resets.

403 Forbidden — Domain not allowed

Message: "Embed requests from this origin are not allowed for this workspace"

The page where the widget is embedded is not in your Allowed domains list. Our backend checks the request Origin or Referer against the domains you configured in Workspace Settings.

What to do: Add the domain (e.g. example.com, www.example.com, or your staging URL) to Allowed domains in Workspace → Widget/Embed settings. See Allowed domains.

401 Unauthorized

Message: "workspace API key is required" or "Invalid workspace API key provided"

The publishable key is missing, invalid, or does not match the workspace/bot in the request.

What to do: Ensure the widget snippet includes the correct publishable key from Workspace Settings → Publishable Keys. Check that workspace_id and bot_id in the request match the key’s workspace.

404 Not Found

The bot or workspace was not found. This can happen if the bot was deleted, the IDs in the snippet are wrong, or the workspace was removed.

What to do: Verify the workspace and bot IDs in your embed snippet. Ensure the assistant is published and active.

400 Bad Request

Validation failed. Common causes:

• "User message exceeds maximum allowed content length" — The user’s message is too long. Shorten it or adjust your UI.
• "Invalid workspace ID" or invalid request body — Check that workspace_id, bot_id, and user_message are present and valid.

422 Unprocessable Entity

Request body validation failed (e.g. missing required fields, wrong types).

What to do: Ensure the request includes workspace_id, bot_id, and user_message in the expected format.

500 / 503 Internal Server Error / Service Unavailable

A server-side error occurred. If it persists, contact support.

Widget does not load

• Check allowed domains — The most common cause. Add your domain to Allowed domains.
• Check the snippet — Ensure window.ChatHQ.workspace, window.ChatHQ.bot, and window.ChatHQ.publishableKey are set correctly before the script loads.
• Check the browser console — Look for 403, 401, or 429 errors and their messages.
• Development mode —

Usage limits and plan upgrades

When you exceed your workspace plan’s usage limits, you will receive 429 with reason: daily_limit_exceeded or reason: minute_limit_exceeded. The response details include your current usage and reset times. Upgrade your plan in Workspace → Plan for higher limits.