API Reference
Status Codes
HTTP status codes used by the RealtimeX API and how your client should react.
Overview
RealtimeX uses standard HTTP status codes together with the JSON response envelope. Treat the status as the primary signal for control flow (retry, re-auth, show validation errors), and use message for human-readable detail.
Most successful reads and updates return 200. Creates often return 201. Client mistakes land in the 4xx range; unexpected failures return 500.
Endpoint pages list the statuses you are most likely to see for that call. This page is the complete cross-API reference.
Success codes
| HTTP Status | Meaning | When you see it |
|---|---|---|
| 200 | OK | Request succeeded for GET, PATCH, PUT, or DELETE. Body usually includes success: true and a data payload. |
| 201 | Created | A new resource was created successfully (POST) — for example register client, create role, or create group. |
Client errors (4xx)
4xx means the request should not be blindly retried without a change (except 429 after backoff, and 401 after refreshing the token).
| HTTP Status | Meaning | When you see it |
|---|---|---|
| 400 | Bad Request | Validation failed, required fields are missing, types are wrong, or a value exceeds plan limits (settings, mute minutes, etc.). |
| 401 | Unauthorized | Missing, invalid, or expired Bearer token. Refresh the access token or sign in again. |
| 403 | Forbidden | Authenticated but not allowed — for example missing tenant admin privileges on Platform endpoints, or locked group permissions. |
| 404 | Not Found | The requested resource does not exist (conversation, message, user, role, report, etc.) or the id is invalid. |
| 409 | Conflict | The request conflicts with current state — duplicate email/slug, role still assigned to users, and similar cases. |
| 422 | Unprocessable Entity | The request was well-formed JSON but failed a business rule the server cannot apply. |
| 429 | Too Many Requests | Rate limit exceeded. Back off and retry; check any X-RateLimit-* response headers when present. |
Typical 401 body
json
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}Server errors (5xx)
| HTTP Status | Meaning | When you see it |
|---|---|---|
| 500 | Internal Server Error | Unexpected server-side failure. Retry once; if it persists, contact support with the request id / timestamp. |
Full reference table
| HTTP Status | Message | Seen on |
|---|---|---|
| 200 | OK | Request succeeded for GET, PATCH, PUT, or DELETE. Body usually includes success: true and a data payload. |
| 201 | Created | A new resource was created successfully (POST) — for example register client, create role, or create group. |
| 400 | Bad Request | Validation failed, required fields are missing, types are wrong, or a value exceeds plan limits (settings, mute minutes, etc.). |
| 401 | Unauthorized | Missing, invalid, or expired Bearer token. Refresh the access token or sign in again. |
| 403 | Forbidden | Authenticated but not allowed — for example missing tenant admin privileges on Platform endpoints, or locked group permissions. |
| 404 | Not Found | The requested resource does not exist (conversation, message, user, role, report, etc.) or the id is invalid. |
| 409 | Conflict | The request conflicts with current state — duplicate email/slug, role still assigned to users, and similar cases. |
| 422 | Unprocessable Entity | The request was well-formed JSON but failed a business rule the server cannot apply. |
| 429 | Too Many Requests | Rate limit exceeded. Back off and retry; check any X-RateLimit-* response headers when present. |
| 500 | Internal Server Error | Unexpected server-side failure. Retry once; if it persists, contact support with the request id / timestamp. |
Handling guide
| Status | Recommended client behavior |
|---|---|
| 200 / 201 | Update UI from data. Optionally show message as a success toast. |
| 400 / 422 | Highlight invalid fields; do not retry until the user or client fixes the payload. |
| 401 | Attempt token refresh; if that fails, redirect to login. |
| 403 | Show an access-denied state. Check role, tenant headers, and whether the endpoint requires Platform admin. |
| 404 | Remove stale rows from caches/lists; offer to go back or refresh. |
| 409 | Explain the conflict (duplicate slug, role in use) and suggest a remediating action. |
| 429 | Back off exponentially; respect rate-limit headers when present. |
| 500 | Retry once with jitter; if it persists, surface a generic error and capture diagnostics for support. |
Best practices
- Centralize status handling in your API client so every screen behaves consistently on 401/403/404.
- Pair status handling with envelope parsing — see Sample responses.
- Do not treat every non-200 as fatal; some flows expect 409 and should guide the user to resolve the conflict.
- For idempotent GETs, safe retries on 500/429 are fine; for POSTs, confirm whether a retry could create duplicates.