Errors
Every error code the engine and the kits use: what it means and what to do.
Applies to: engine API v1, utd_audio_room_kit 3.14.1, utd_live_room_kit 3.11.0
Rely on the HTTP status, plus the code field when it is present. code is additive: some responses carry none, and the message text may be reworded, so never branch on the message. A code your integration does not know is a normal case: fall back to the status.
HTTP 403
{ "code": "appkey_identity_mint_disabled",
"message": "Minting an identity-bearing token with the publishable app_key is disabled for this project. ..." }The Action column is what the kits do and what you should do: fix means your integration is wrong and retrying unchanged is useless; retry means transient, back off; stop means final for this request or session; refresh means mint a new token and try once; support means the project owner contacts UTD support.
401: credentials and sessions
| Code | Meaning | Action |
|---|---|---|
token_expired | The user_token lifetime ended. | refresh |
session_superseded | The user signed in on another device. Show a "signed in elsewhere" state. | stop (do not reconnect automatically) |
missing_credentials | App ID/key or user-token headers are missing. | fix |
invalid_credentials | Unknown App ID, or key/secret mismatch. If you rotated the App Key, ship the new one. | fix |
invalid_user_token | The user_token is malformed, altered, or not for this project. | refresh |
client_secret_disabled | The project accepts user tokens only. Call the route with a user token, not the secret. | fix |
403: not allowed
| Code | Meaning | Action |
|---|---|---|
appkey_identity_mint_disabled | You minted a user token with the App Key. Mint from your backend with the Server Secret. | fix |
room_type_disabled, streaming_disabled | That room type or service is not enabled for the project. A configuration problem, never a message about the user. | stop |
user_banned | The user is banned from this room or the project. The only code that should show a "you were removed" message. | stop |
origin_not_allowed | The browser Origin is not on the project's allow list. | fix |
feature_not_enabled | The service (messaging, PK, signaling) is not enabled for the project. | stop |
client_suspended | The whole client account is suspended. | support |
project_suspended, project_suspended_balance, project_suspended_unpaid, project_suspended_manual, project_suspended_abuse | The project is suspended. The cause is visible to your backend only; show the user a neutral "room unavailable". | support (do not retry in a loop) |
409 and 422: the request
| Code | Meaning | Action |
|---|---|---|
idempotency_key_reused | The same Idempotency-Key was sent with a different request. Use a fresh key per action. | fix |
room_full | The room is at its participant limit (409). Returned only where full-room enforcement is on for the project. Show a "room is full" message. | stop |
missing_room_or_user_id | user_id or room_id is missing (the older identity and room_name are still accepted). | fix |
invalid_parameter | A field is missing or invalid; the response names it in param. | fix |
device_id_required | The project requires device_id. Send a stable per-install id. | fix |
429: limits
| Code | Meaning | Action |
|---|---|---|
project_rate_limited | The project-wide REST budget (600 per minute by default). | retry |
user_rate_limited | One user's REST budget (120 per minute by default). | retry |
token_rate_limited | Token requests for one user and device (30 per minute). | retry (do not loop) |
identity_rate_limited | Token requests for one user_id across devices (100 per minute). | retry |
report_rate_limited | Quality reports: 1 per 10 seconds per identity. | retry |
session_cooldown | A different device tried to take over a session established in the last 10 seconds. The existing session is kept. | retry after a few seconds |
max_concurrent_rooms | The project's cap on concurrent rooms. It does not clear by waiting. | stop |
pk_reinvite_cooldown | A PK battle re-invite came too soon. | retry later |
rate_limited | A generic limit, for example the channel or client-event limit. | retry |
5xx and network
| Code | Meaning | Action |
|---|---|---|
token_generation_failed | The engine could not sign the media token. | retry; report to UTD if it persists |
internal_error | Unexpected failure in the authentication step. | retry; report to UTD if it persists |
request_timeout | The engine time limit was exceeded. | retry |
media_update_failed | The media server refused a mute or role update (502). The participant's state did not change. | retry after a short backoff |
network_error | Raised by the kit, never sent by the engine: no HTTP response at all (offline, DNS, TLS). | retry |
Reading the code in the kits
try {
final res = await controller.generateToken(identity: 'u1', roomName: 'lobby', roomOwnerId: 'owner');
} catch (e) {
final code = utdErrorCodeOf(e); // 'user_banned', 'token_rate_limited', 'network_error', ...
final info = utdErrorInfo(code);
showSnack(info.message('en')); // safe to show an end user: never mentions billing or credentials
print(info.hint('en')); // for your logs: what to fix
if (info.retryable) scheduleRetryWithBackoff();
}message(lang) accepts en and ar; any other language, and Hindi until its text is reviewed, gives English. Seat operations have their own client-side codes on UTDSeatController.lastSeatError: connecting (the session is still connecting; try again shortly) and not_connected (rejoin the room first). They mean the engine was never asked. An engine refusal such as a seat that is taken or locked keeps returning false with no code.
The signaling WebSocket reports errors as ack codes, not HTTP statuses. The server-to-server action API reports them in the Code field of its response envelope.
Ready to build with UTD?
Create your account, fund your master wallet, and turn on the services you need.