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.
UTD ile inşa etmeye hazır mısınız?
Hesabınızı oluşturun, ana cüzdanınızı fonlayın ve ihtiyacınız olan hizmetleri açın.