Oracle Radio API Errors
Handle Radio failures according to authentication, authorization, request, state, throttling, and service categories.
REST Errors
Inspect operation-specific JSON results as well as HTTP status. Geofence deletion can return HTTP 200 with type set to ERROR; a successful location update can include unsuccessful subscription actions.
| Error | Client action |
|---|---|
400 request error | Correct the documented request property, query value, or path identifier before retrying. |
401 authentication error | Obtain or renew a supported credential by using the correct authentication path. Do not retry the same invalid credential repeatedly. |
404 NotAuthorizedOrNotFound | The response message is Authorization failed or requested resource not found. Verify the identifier and have an authorized administrator verify that the Radio user is enabled and has the required permission and channel access. Don't retry the unchanged request repeatedly. |
409 conflict | Refresh current state before deciding whether to retry. For super_admin_protected, keep the designated user enabled and in Radio Administrators. A system-group conflict means its name, status, permissions, or deletion is protected; change only permitted membership. Don't retry the same protected change. See protected access and recovery guidance. |
429 throttling | Back off and honor the documented retry interval. |
503 dependency unavailable | Retry with bounded exponential backoff when the operation is safe to repeat. |
For Radio REST operations that use NotAuthorizedOrNotFound, an authorization failure and a missing or unavailable resource intentionally have the same response. Don't use this response to infer whether the requested resource exists. This REST behavior doesn't replace the operation-specific denial results returned by the WebSocket API.
If a request that previously matched the published schema is rejected after a client or service change, follow the compatibility checks before changing the request.
WebSocket Errors and Outcomes
A WebSocket connection carries direct responses and asynchronous events, so not every unsuccessful outcome is a protocol error. Match the returned type to the operation topic before changing client state.
| Result | Meaning | Client action |
|---|---|---|
AUTH_ERROR | The access token wasn't accepted, a renewal represented another principal, or a gateway-authenticated browser connection sent AUTH. | If initial authentication fails, wait for successful authentication before sending other Radio operations. Correct the supported authentication path. A rejected renewal doesn't replace the previously accepted session or extend its expiry; authorized operations can continue while that session remains valid. If a gateway-authenticated browser connection sends AUTH, stop sending AUTH; the accepted browser session remains unchanged. |
ERROR with AUTH_REQUIRED | A bearer-token connection sent a product message or binary audio before authentication. | Send AUTH, wait for AUTH_SUCCESS, and then send the operation again. A PONG response alone doesn't authenticate the session. |
ERROR | The JSON message is invalid, a required property or state is missing, the requested item is unavailable, or the operation otherwise couldn't be processed. | Use the returned customer-visible message and the operation's parameter table to correct the request or state before retrying. Do not treat ERROR as a successful confirmation. |
| Permission denial | A denial such as SUBSCRIBE_DENIED with PERMISSION_DENIED or TALK_DENIED can mean that the authenticated Radio user lacks an operation permission. | Use the returned reason and code to identify the missing permission. Do not repeat the operation until the user's Radio permissions allow it. |
Text-message ERROR with NotAuthorizedOrNotFound | The message is Authorization failed or requested resource not found. The response deliberately omits the channel and reason; it doesn't distinguish permissions, channel access, membership, or resource absence. | Match the supplied clientMessageId to the pending request. Verify the target and subscription, and have an authorized administrator check access. After correcting a confirmed rejection, use a new identifier for a deliberate new attempt; the old identifier can replay the cached error. See message troubleshooting. |
| Channel-access denial | SUBSCRIBE_DENIED with ACL_DENIED, a denied per-channel subscription result, or another access-denial result means the connection didn't join or use the requested channel. | Use the returned reason and code to distinguish this result from a missing operation permission. Do not use that channel for dependent operations. Verify channel access, then send the subscription operation again and wait for a successful result. |
DENIED | The talk-floor request wasn't granted, typically because the channel is busy. This result is not a talk-floor grant. | Do not send START or binary audio. Use the returned busy-holder or reason information, if present, to decide whether to send another REQUEST_TALK later. |
QUEUED | The talk-floor request is waiting behind the current holder. This result is not a grant and is not an error. | Do not send START or binary audio. Wait for a later GRANTED result, or discard the queued state if the connection closes. |
TOKEN_INVALID or TOKEN_EXPIRED | The connection doesn't hold a usable talk token. An expiration can arrive asynchronously during transmission. | Stop sending audio immediately and discard the token. If transmission is still needed, begin again with REQUEST_TALK. |
INTERRUPTED | A higher-priority user took the talk floor. | Stop sending audio immediately, discard the interrupted token, and request a new token before another transmission. |
| WebSocket close result | The WebSocket connection ended. The close can follow authentication, network, service, or client conditions, and the public contract doesn't define automatic restoration of prior live state. | Stop sending, record the customer-visible close result, and don't assume that channel memberships, a presence subscription, or a talk token can be reused. Correct an authentication or authorization problem before reconnecting. Otherwise, reconnect with backoff and rebuild and verify required live state. The API doesn't define a fixed retry interval or a guaranteed close-code mapping. |
An ACL_DENIED response to REQUEST_TALK can also occur when the requested channel is unavailable. The code alone doesn't prove that the channel exists. Have an authorized administrator verify the channel identifier and access before you retry. See talk guidance.
For the recovery sequence, see Workflow: Managing an Oracle Radio WebSocket Session. For operation-specific response properties, see Oracle Radio WebSocket Message Families.
More Help
If the returned result doesn't identify the corrective action, use troubleshooting. For common questions about authentication, access, retries, and WebSocket state, see the FAQ.