Developer guide

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.

error response
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

CodeMeaningAction
token_expiredThe user_token lifetime ended.refresh
session_supersededThe user signed in on another device. Show a "signed in elsewhere" state.stop (do not reconnect automatically)
missing_credentialsApp ID/key or user-token headers are missing.fix
invalid_credentialsUnknown App ID, or key/secret mismatch. If you rotated the App Key, ship the new one.fix
invalid_user_tokenThe user_token is malformed, altered, or not for this project.refresh
client_secret_disabledThe project accepts user tokens only. Call the route with a user token, not the secret.fix

403: not allowed

CodeMeaningAction
appkey_identity_mint_disabledYou minted a user token with the App Key. Mint from your backend with the Server Secret.fix
room_type_disabled, streaming_disabledThat room type or service is not enabled for the project. A configuration problem, never a message about the user.stop
user_bannedThe user is banned from this room or the project. The only code that should show a "you were removed" message.stop
origin_not_allowedThe browser Origin is not on the project's allow list.fix
feature_not_enabledThe service (messaging, PK, signaling) is not enabled for the project.stop
client_suspendedThe whole client account is suspended.support
project_suspended, project_suspended_balance, project_suspended_unpaid, project_suspended_manual, project_suspended_abuseThe 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

CodeMeaningAction
idempotency_key_reusedThe same Idempotency-Key was sent with a different request. Use a fresh key per action.fix
room_fullThe 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_iduser_id or room_id is missing (the older identity and room_name are still accepted).fix
invalid_parameterA field is missing or invalid; the response names it in param.fix
device_id_requiredThe project requires device_id. Send a stable per-install id.fix

429: limits

CodeMeaningAction
project_rate_limitedThe project-wide REST budget (600 per minute by default).retry
user_rate_limitedOne user's REST budget (120 per minute by default).retry
token_rate_limitedToken requests for one user and device (30 per minute).retry (do not loop)
identity_rate_limitedToken requests for one user_id across devices (100 per minute).retry
report_rate_limitedQuality reports: 1 per 10 seconds per identity.retry
session_cooldownA 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_roomsThe project's cap on concurrent rooms. It does not clear by waiting.stop
pk_reinvite_cooldownA PK battle re-invite came too soon.retry later
rate_limitedA generic limit, for example the channel or client-event limit.retry

5xx and network

CodeMeaningAction
token_generation_failedThe engine could not sign the media token.retry; report to UTD if it persists
internal_errorUnexpected failure in the authentication step.retry; report to UTD if it persists
request_timeoutThe engine time limit was exceeded.retry
media_update_failedThe media server refused a mute or role update (502). The participant's state did not change.retry after a short backoff
network_errorRaised by the kit, never sent by the engine: no HTTP response at all (offline, DNS, TLS).retry

Reading the code in the kits

Dart
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 দিয়ে গড়তে প্রস্তুত?

আপনার অ্যাকাউন্ট তৈরি করুন, মাস্টার ওয়ালেট ফান্ড করুন, এবং প্রয়োজনীয় সার্ভিসগুলো চালু করুন।