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

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

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.

Overview

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.

HTTP Status

Meaning

When you see it

200

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.