Errors
Every non-2xx response has the same body. error is a stable snake_case code you can branch on. message is for people and may change.
{ "status_code": 403, "error": "missing_capability", "message": "Missing Chat capability messages.send", "path": "/api/v1/tenants/fitness/applications/fitness-app/conversations/6b1f4c7e-3c52-4a0a-9a39-7d2e2f1f8a10/messages", "timestamp": "2026-10-14T09:30:00.000Z"}messageis a string, or an array of strings when several request fields are invalid.- A
429response carries aRetry-Afterheader with the seconds to wait. - Retry
429,500and503with backoff. Do not retry other4xxresponses without changing the request. - The SDKs raise a typed error per status. Each carries
.statusand.code, theerrorvalue. See Errors and Handle errors and retries.
Codes marked “Chat web sign-in only” are returned by the routes of Chat’s own web client. Tenant applications never call those routes.
400 Bad request
body_too_long
When. The message body is longer than the maximum message length.
What to do. Shorten the message or split it. The maximum is on the Limits page.
Returned by. Send a message, Edit a message
invalid_cursor
When. The before cursor is not one this list issued.
What to do. Pass the next_cursor of the previous page unchanged, or omit before to start from the newest item.
Returned by. List conversations, List members, List messages, Every conversation of the tenant (moderation), Audit log
invalid_grant
When. An OAuth grant was refused. Chat's own web sign-in returns it for an invalid, expired or already used code or refresh token. Your backend also meets it from the Identity Server when a token exchange fails because the user's own token expired or their session ended.
What to do. Renew the user's own token (sign in again), then retry the exchange. See the Identity Server token exchange documentation.
invalid_id_token
When. Chat web sign-in only: the ID token returned by the Identity Server failed validation.
What to do. Not used by tenant applications. Retry the sign-in.
invalid_json
When. The request body is not valid JSON.
What to do. Send well-formed JSON with Content-Type: application/json.
invalid_limit
When. limit is not a positive integer.
What to do. Send an integer from 1 to 100.
Returned by. List conversations, List members, List messages, Every conversation of the tenant (moderation), Audit log
invalid_redirect_uri
When. Chat web sign-in only: the redirect_uri is not registered for Chat web.
What to do. Not used by tenant applications.
invalid_request
When. The request is malformed: a required field is missing, a value has the wrong type or format, or a field the route does not accept was sent. message lists every problem.
What to do. Fix the request body or parameters named in message and retry.
Returned by. Register a push device, List conversations, Create a conversation, Update a conversation, Add a member, Send a message, Edit a message, Add a reaction, Replace a role's Chat capabilities in one context, Update Chat settings
query_too_long
When. The user lookup query q is longer than the maximum.
What to do. Shorten the query.
Returned by. Look up tenant members
query_too_short
When. The user lookup query q has fewer than 2 characters.
What to do. Send at least 2 characters.
Returned by. Look up tenant members
role_locked
When. Administration: the role cannot be changed (the tenant owner always holds every permission).
What to do. Change another role.
Returned by. Replace a role's Chat capabilities in one context
too_many_attachments
When. The message has more attachments than the maximum per message.
What to do. Send fewer attachments per message. The maximum is on the Limits page.
Returned by. Send a message
user_required
When. A machine token called a route that acts as a signed-in user (reactions, read state, typing).
What to do. Call this route with a user token. Machine clients cannot react, mark read or type.
Returned by. Add a reaction, Remove a reaction, Mark read, Signal typing
401 Unauthorized
invalid_token
When. The bearer token is missing, malformed, expired, signed by an unknown key, has the wrong audience (aud must be chat-api), or lacks the required scope.
What to do. Get a token for the Chat API resource: request it with resource set to the Chat API resource identifier, not the audience. A token issued for your own API is rejected. Renew an expired token.
Returned by. Any authenticated route.
token_revoked
When. The token was revoked at the Identity Server (sign-out, user disabled, removed from the tenant). Only checked on administration writes when strict revocation is on.
What to do. Sign the user in again or exchange a fresh token.
Returned by. Any authenticated route.
403 Forbidden
chat_access_not_granted
When. Chat web sign-in only: the Identity Server did not grant the user a Chat access token (audience chat-api, scope chat:access).
What to do. Not used by tenant applications. Check that the user may use the Chat platform application in the Identity Server.
client_context_mismatch
When. The token was issued to a client of another tenant or application than the one in the URL. Machine tokens and tokens of a tenant application's client work only in their own context.
What to do. Use the tenant_id and application_id of the application whose client issued the token. For an exchanged token that is your backend client's application.
Returned by. Any authenticated route.
insufficient_scope
When. A machine token does not carry a scope that grants the route's capability, or a user token lacks chat:access.
What to do. Request the missing scope (chat:sync or the granular scope) and make sure the client is granted it on the Chat API resource at the Identity Server.
Returned by. Any authenticated route.
missing_capability
When. The caller lacks the Chat permission (capability) the route needs, in this tenant application. message names it.
What to do. A tenant administrator grants the capability to the caller's role in Chat Administration, for this application. Machine clients: grant the scope that carries it; some capabilities are never available to machines.
Returned by. Any authenticated route.
no_application_access
When. The user has no access to the application in the URL.
What to do. Give the user access to the application in the Identity Server, then retry.
Returned by. Any authenticated route.
not_conversation_member
When. The user is not an active member of the conversation (and it is not a PUBLIC channel).
What to do. Add the user to the conversation (from your backend), or have them join a PUBLIC channel.
Returned by. Get a conversation, List messages, Send a message, Add a reaction, Remove a reaction, Mark read, Signal typing
not_tenant_member
When. The user is not an active member of the tenant in the URL.
What to do. Check the tenant_id and the user's membership in the Identity Server.
Returned by. Any authenticated route.
principal_not_allowed
When. The route does not accept this kind of token: user-only routes reject machine tokens.
What to do. Call the route with a user token (for example one obtained by token exchange).
Returned by. Any authenticated route.
system_message_not_allowed
When. A user tried to send a SYSTEM message. Only machine clients may.
What to do. Send SYSTEM messages from your backend with the machine client.
Returned by. Send a message
tenant_not_available
When. The tenant is not active or has Chat switched off.
What to do. Check the tenant status in the Identity Server.
Returned by. Any authenticated route.
404 Not found
application_not_found
When. The application does not exist in the tenant, or Chat is not enabled for it.
What to do. Check application_id and that Chat is enabled for the application.
Returned by. Any authenticated route.
not_found
When. The resource does not exist, or belongs to another tenant or application. Chat does not reveal which.
What to do. Check the ids and the context in the URL.
Returned by. Any authenticated route.
role_not_found
When. Administration: the role is not part of the chosen context.
What to do. List the roles for the context first and use one of them.
Returned by. Replace a role's Chat capabilities in one context
413 Payload too large
payload_too_large
When. The request body is larger than 256 kB.
What to do. Send a smaller body.
422 Unprocessable
actor_not_member
When. The actor_user_id of an on-behalf-of message is not a member of the conversation.
What to do. Add the user to the conversation first, or send as another member.
Returned by. Send a message
conversation_archived
When. Someone tried to post to an archived conversation. Archived conversations are read-only.
What to do. Reactivate the conversation from your backend if the relationship resumes.
Returned by. Send a message
direct_conversation_immutable
When. Someone tried to change a DIRECT conversation other than its status, or a user tried to change its status.
What to do. DIRECT conversations only change status, and only a machine client may do that.
Returned by. Update a conversation
invalid_reply
When. reply_to_message_id does not name a message of the same conversation.
What to do. Reply to a message of the same conversation.
Returned by. Send a message
target_user_not_eligible
When. A user you referenced (member, actor) is not an active member of the tenant with access to the application.
What to do. Check the user's membership and application access in the Identity Server. A user newly added there becomes visible to Chat within the identity cache time.
Returned by. Create a conversation, Add a member, Send a message
429 Too many requests
rate_limited
When. The caller exceeded a rate limit. The Retry-After header says how many seconds to wait.
What to do. Wait Retry-After seconds and retry. Reduce the request rate. Limits are on the Limits page.
Returned by. Any authenticated route.
500 Server error
server_error
When. An unexpected error in Chat.
What to do. Retry with backoff. If it persists, contact support with the timestamp and path of the response.