API Reference
Error Codes
Understand RealtimeX API errors, read the response envelope, and look up common messages by endpoint.
Overview
When a request fails, RealtimeX returns a consistent JSON error envelope so your application can handle failures the same way across every endpoint.
Each error includes an HTTP status code and a clear message describing what went wrong. Use the status code to decide how to recover, and use the message to show useful feedback to users or logs.
Success and error responses share the same top-level shape. Check success first, then read message and error when the request fails.
Error Response Format
Failed requests return a body similar to the example below:
{
"success": false,
"message": "Human-readable error message",
"data": null,
"error": "Optional error detail or null"
}Field reference
| Field | Description |
|---|---|
| success | Always false for error responses. |
| message | A human-readable summary of the failure. Safe to surface in UI copy or logs. |
| data | Typically null when the request fails. |
| error | Optional extra detail for debugging. May be a short label, validation hint, or null. |
How to Handle Errors
A simple, reliable approach for client integrations:
- Inspect the HTTP status code to choose the recovery path (retry, re-authenticate, fix input, or show a not-found state).
- Read
messagefor the exact reason returned by the API. - Map common messages to user-friendly copy in your product UI when needed.
- Log the full response (status, message, and error) for support and debugging—without storing sensitive tokens.
Common Error Codes
The table below lists frequently observed error messages across the RealtimeX API, along with the HTTP status and the endpoints where they commonly appear.
| HTTP Status | Message | Seen On |
|---|---|---|
| 400 | Current password is incorrect | Change Password |
| 400 | No editable fields provided | Update Conversation |
| 400 | conversationIds must be 1-100 valid ids | Bulk Delete Conversations |
| 400 | System messages cannot be edited | Update Message |
| 400 | messageIds must be 1-100 valid ids | Bulk Delete Messages |
| 400 | Invalid role | Update User |
| 400 | userIds must be 1-100 valid ids | Bulk Delete Users |
| 400 | Invalid tenant ID or isTenant header | Login Client User |
| 400 | Provide at least one of: name, profileImage | Update My Profile |
| 400 | No files provided | Get Presigned URLs (S3 Upload) |
| 401 | No token, authorization denied | Get My Profile, Update My Profile +4 more |
| 401 | Session expired | Is Logged In |
| 403 | Access denied: insufficient permissions | Login Client User |
| 403 | Access denied: tenant admin privileges required | Dashboard Overview, Analytics Overview |
| 404 | Conversation not found | Delete Conversation, Conversation Attachments +1 more |
| 404 | Message not found | Delete Message |
| 404 | Entity not found | User Role - Get By Id |
| 409 | A client with this email already exists | Update Profile |
| 409 | Email already in use by another user | Update User |
| 409 | Cannot delete: 3 user(s) still assigned this role | User Role - Delete |
Status Categories
Use these categories as a quick guide when deciding how your application should respond.
Bad Request
The request was malformed or missing required fields. Check the payload, headers, and parameter constraints before retrying.
Unauthorized
Authentication failed. Refresh or re-issue the access token, then retry the request with a valid Authorization header.
Forbidden
The caller is authenticated but does not have permission. Confirm the user role, tenant privileges, and endpoint scope.
Not Found
The requested resource does not exist or is no longer available. Verify the ID and that the resource has not been deleted.
Conflict
The request conflicts with the current state of the resource—for example, a duplicate email or a role still assigned to users.
Best Practices
- Always handle both the HTTP status and the JSON
messagefield. - For
401responses, attempt a token refresh before forcing the user to log in again. - Treat
409conflicts as actionable user feedback (for example, “email already in use”). - Do not retry
400or403errors without changing the request. - Prefer showing the API
messagewhen it is already clear; otherwise map it to friendlier product copy.