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:

json

1{2  "success": false,3  "message": "Human-readable error message",4  "data": null,5  "error": "Optional error detail or null"6}

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 message for 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.

400

Bad Request

The request was malformed or missing required fields. Check the payload, headers, and parameter constraints before retrying.

401

Unauthorized

Authentication failed. Refresh or re-issue the access token, then retry the request with a valid Authorization header.

403

Forbidden

The caller is authenticated but does not have permission. Confirm the user role, tenant privileges, and endpoint scope.

404

Not Found

The requested resource does not exist or is no longer available. Verify the ID and that the resource has not been deleted.

409

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 message field.
For 401 responses, attempt a token refresh before forcing the user to log in again.
Treat 409 conflicts as actionable user feedback (for example, “email already in use”).
Do not retry 400 or 403 errors without changing the request.
Prefer showing the API message when it is already clear; otherwise map it to friendlier product copy.