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 کے ساتھ تعمیر کے لیے تیار ہیں؟

اپنا اکاؤنٹ بنائیں، اپنے ماسٹر والٹ کو فنڈ کریں، اور جن سروسز کی ضرورت ہے انہیں آن کریں۔