Rate limits

Understand how ChatHQ enforces rate limits for the widget and API, and what happens when you exceed them.

Types of rate limiting

Rate limiting happens at two main levels:

• Workspace-based limits — Apply per workspace and are tied to your subscription plan. These control how many runtime messages your assistants can process per minute and per day.
• Global IP-based throttling — Applies across the API to protect the platform from abuse. This is not specific to a single workspace; it limits how frequently a single IP can call the API.

Workspace-based limits (per plan)

Every workspace has a plan (Free, Paid, etc.) with associated usage limits. The backend enforces these using the WorkspaceRateLimitService:

• Per-minute limit — Maximum number of runtime messages your workspace can send in a rolling minute.
• Per-day limit — Maximum number of runtime messages your workspace can send in a calendar day.

When a request arrives at POST /api/v1/runtime/messages:

1. We look up your workspace and its plan’s rate limit configuration.
2. We track usage for that workspace in Redis and the database.
3. If usage is within limits, the request is allowed.
4. If usage exceeds the per-minute or per-day limit, we return 429 Too Many Requests with details.

The response body for plan-based rate limits includes:

• reason — minute_limit_exceeded or daily_limit_exceeded
• currentUsagePerMinute / limitPerMinute
• currentUsagePerDay / limitPerDay
• resetAtPerMinute / resetAtPerDay

Use these fields to understand when you can resume sending traffic or whether you should upgrade your plan.

Global IP-based throttling

In addition to workspace limits, we apply global throttling using NestJS’s @nestjs/throttler:

• Requests are grouped by a tracker:
  • Authenticated requests → user:{userId}
  • Requests with x-workspace-id header → workspace:{workspaceId}:{ip}
  • All other requests → ip:{ip}
• Default throttler levels (configurable via environment variables):
  • Short window (e.g. 20 requests per second)
  • Medium window (e.g. 100 requests per minute)
  • Long window (e.g. 1000 requests per hour)

When these limits are hit, we return 429 Too Many Requests with a generic message:

Too many requests. Please try again later.

This throttling protects the platform globally (e.g. from sudden traffic spikes or abusive scripts) and is not tied to your workspace plan.

Error codes and behavior

429 Too Many Requests