Rate limits & errors
When something goes wrong, CXGear prefers a clear error over a silent failure. This page helps integrators and admins read those responses and decide what to do.
How errors are shaped
Section titled “How errors are shaped”Most JSON error bodies include at least:
| Field | Meaning |
|---|---|
| error or message | Human-readable explanation |
| errorCode | Machine-stable code when applicable (for example PLAN_LIMIT) |
Always log the status code, errorCode, and message. Retry logic should depend on the code, not only on “request failed.”
PLAN_LIMIT
Section titled “PLAN_LIMIT”Your organization hit a subscription limit.
| Property | Typical value |
|---|---|
| errorCode | PLAN_LIMIT |
| HTTP status | 403 |
| Meaning | Action blocked by plan meters (projects, jobs/month, users, API keys, …) |
Example situations:
- Creating a second project on Trial
- Starting a job when monthly jobs are exhausted
- Creating an API key when the key cap is reached
- Triggering a spinner via the public API when records/month is full
What to do: open Billing → Usage, free capacity, or upgrade. Do not retry in a tight loop — the limit will not clear until usage or plan changes (monthly meters also reset on the 1st).
See When a limit is hit.
src/assets/screenshots/10-billing-usage.pngSession and auth errors
Section titled “Session and auth errors”Interactive clients use user JWTs tied to a single active session.
| Symptom | Meaning | What to do |
|---|---|---|
| Session expired | Token or session timed out | Sign in again |
| Session revoked | Logout, password reset, or admin action | Sign in again |
| Session replaced | Same account signed in elsewhere | Expected under single-session policy |
| Token invalid / missing | Bad or absent Authorization header | Refresh login or fix the client |
The web app maps these to friendly banners on the login screen (for example “Your session has expired. Please sign in again.”).
For automation, do not use user JWTs. Use organization API keys so a person signing in on another device does not break your CRM integration.
Session conflict details: Single active session.
Public API auth errors
Section titled “Public API auth errors”| Status | Message pattern | Cause |
|---|---|---|
| 401 | Invalid API key | Missing/wrong/revoked key |
| 403 | Key missing ingest scope | Key lacks ingest |
| 403 | Key missing trigger scope | Key lacks trigger |
| 403 | PLAN_LIMIT | Plan meter full |
| 404 | Data table / spinner not found | Wrong id or not published |
| 400 | Invalid body | JSON shape wrong |
| 400 | SCHEMA_MISMATCH | Ingest columns do not match table |
| 400 | NO_SCHEMA | Table has no schema yet — import CSV first |
Common HTTP status codes
Section titled “Common HTTP status codes”| Code | Usual meaning in CXGear |
|---|---|
| 200 | Success (read or update) |
| 201 | Created (for example job from trigger) |
| 400 | Bad request — fix the payload |
| 401 | Not authenticated — sign in or fix API key |
| 403 | Authenticated but not allowed (permission or plan) |
| 404 | Resource not found or not visible to this org |
| 409 | Conflict (for example session already active on another device) |
| 429 | Too many requests — slow down (platform rate limit) |
| 500 | Unexpected server error — retry with backoff; check status/logs |
403 is overloaded on purpose: it can mean “your role cannot do this” or “your plan cannot do this.” Read errorCode and the message to tell them apart.
Permissions vs plan limits
Section titled “Permissions vs plan limits”| Failure | Who can fix it |
|---|---|
| Missing permission (role) | Admin grants a role or permission |
PLAN_LIMIT | Admin upgrades or frees usage |
A user with full Admin permissions can still receive PLAN_LIMIT on Trial.
Rate limits
Section titled “Rate limits”The API applies general HTTP rate limiting to protect the platform. If you receive 429:
- Back off (wait, then retry with jitter)
- Batch ingest records (up to 500 per request) instead of one row per call
- Prefer spinner schedules over aggressive external polling
Plan meters are not the same as HTTP rate limits. Hitting 50 jobs/month on Trial is PLAN_LIMIT, not 429.
Success looks like
Section titled “Success looks like”- Integrators branch on
errorCode, not only status text PLAN_LIMITroutes humans to Billing- Session errors send people to login, not into a crash loop
- Automation uses API keys and handles 401/403/400 explicitly
Common problems
Section titled “Common problems”| Problem | Likely cause | What to do |
|---|---|---|
| Treating PLAN_LIMIT as 500 | Ignoring errorCode | Map 403 + PLAN_LIMIT to upgrade UX |
| Script breaks when user logs in elsewhere | Using JWT in middleware | Switch to org API key |
| Endless retries | Retrying non-idempotent limit errors | Stop on PLAN_LIMIT and 400 |
| SCHEMA_MISMATCH in production | CRM field rename | Align columns or update table |