All Plans4 min read· Updated 2026-11-18
Errors & Rate Limits
Understand Omni Chat Stack HTTP status codes, JSON error codes, endpoint rate limits, and safe retry strategies.
HTTP status & error code reference
| HTTP Status | Error Code(s) | Meaning & Recommended Action |
|---|---|---|
| 400 | MISSING_FIELDS, INVALID_TYPE, INVALID_MODE, INVALID_WEBHOOK_URL, VALIDATION_ERROR | Fix the request payload or URL validation issue before retrying. |
| 401 | UNAUTHORIZED, INVALID_API_KEY | Verify your JWT access token or oc_... API key header is present and active. |
| 403 | PLAN_UPGRADE_REQUIRED, FORBIDDEN | Endpoint requires a higher plan (e.g., Paid Plan for Developer API/Catalog) or COMPANY_ADMIN role. |
| 404 | NOT_FOUND, ROUTE_NOT_FOUND | Verify the resource ID belongs to your tenant (companyId) and the route path is accurate. |
| 429 | RATE_LIMIT_EXCEEDED | Respect endpoint rate windows using bounded exponential backoff. |
| 502 | WHATSAPP_ERROR | Upstream Meta WhatsApp Cloud API returned an error (e.g., outside 24h session window or invalid recipient). |
Published endpoint rate limits
| Endpoint Group | Window & Limit | Scope |
|---|---|---|
| WhatsApp Template Reads | 60 requests / 1 minute | Per company & user/IP |
| WhatsApp Template Lifecycle (create/sync/delete) | 30 requests / 1 minute | Per company & user/IP |
| WhatsApp History Import & Coexistence Sync | 10 requests / 1 minute | Per company & user/IP |
| Campaign Reporting / Mutations | 60 reads / 30 writes per 1 minute | Per company & user/IP |
| Knowledge Website Scrape | 5 jobs / 1 hour (configurable) | Per company |
| GDPR Export / Erasure | 10 exports / 15 min · 5 erasures / 1 hour | Per company |