Understanding calling codes and subcodes errors

The Calling SDK and respective server infrastructure use a unified framework to represent errors. Using error codes, subcodes, and their corresponding result categories, as a developer you can more easily understand these errors and find explanations as to why they happened and how to mitigate in the future. The details about the error results can be viewed as:

Code Are modeled as 3 digit integers that indicate the response status of a client or server response. They're grouped into:

  • Successful responses (200-299)
  • Client error (400-499)
  • Server error (500-599)

Subcode Are defined as an integer, where each number indicates a unique reason, specific to a group of scenarios or specific scenario outcome.
Message Describes the outcome, and provides hints how to mitigate the issue problem if an outcome is a failure.
ResultCategory - Indicates the type of the error. Depending on the context, the value can be Success, ExpectedError, UnexpectedClientError, or UnexpectedServerError

Important

Functionality described in this article is currently in public preview. This preview version is provided without a service-level agreement, and we don't recommend it for production workloads. Certain features might not be supported or might have constrained capabilities. For more information, see Supplemental Terms of Use for Microsoft Azure Previews.

Understanding calling codes and subcodes errors

Error codes, subcodes, and corresponding result categories help developers identify and diagnose errors. These error codes are exposed through the call.callEndReason property after a call ends.

Error code details include:

Code - are 3 digit integers representing client or server response status. The code categories:

  • Successful responses (200-299)
  • Client error (400-499)
  • Server error (500-599)
  • Global error (600-699)

Subcode - Are defined as an integer, where each number indicates a unique reason, specific to a group of scenarios or specific scenario outcome.

Message - Describes the outcome, and provides hints how to mitigate the problem if an outcome is a failure.

ResultCategory - Indicates the type of the error. Depending on the context, the value can be Success, ExpectedError, UnexpectedClientError, or UnexpectedServerError.

Azure Communication Services Calling SDK client error codes and subcodes

For client errors, if the resultCategories property is ExpectedError, the error is expected from the SDK's perspective. Such errors are commonly encountered in precondition failures, such as incorrect arguments passed by the app, or when the current system state doesn't allow the API call. The application should check the error reason and the logic for invoking API.

Subcode Code Message Result category Advice
40101 408 Failed to create CallAgent. Try again, if issue persists, gather browser console logs, .HAR file, and contact Azure Communication Services support. UnexpectedClientError
40104 408 Failed to create CallAgent. Try again, if issue persists, gather browser console logs, .HAR file, and contact Azure Communication Services support. UnexpectedClientError
40114 408 Failed to connect to Azure Communication Services infrastructure. Try again and check the browser's network requests. If the requests keep failing, gather browser console logs, .HAR file, and contact Azure Communication Services support. UnexpectedClientError For more information, see network requirements.
40115 412 Failed to create CallAgent, unable to initialize connection to Azure Communication Services infrastructure. Try again and check the browser's network requests. If the requests keep failing, gather browser console logs, .HAR file, and contact Azure Communication Services support. UnexpectedClientError For more information, see network requirements.
40216 500 Failed to create CallAgent. Try again, if issue persists, gather browser console logs and contact Azure Communication Services support. UnexpectedClientError
40228 409 Failed to create CallAgent, an instance of CallAgent associated with this identity already exists. Dispose the existing CallAgent, or create a new one with a different identity. ExpectedError
40230 409 Failed to create TeamsCallAgent, an instance of TeamsCallAgent associated with this identity already exists. Dispose the existing TeamsCallAgent before creating a new one. ExpectedError
40606 405 Failed to enumerate speakers, it isn't supported to enumerate/select speakers on Android Chrome, iOS Safari, nor macOS Safari. ExpectedError Speaker enumeration/selection isn't supported on Android Chrome, iOS Safari, nor macOS Safari. The operating system automatically selects the speaker (output device).

Learn more about device management and how to best mitigate these issues.
40613 400 Failed to obtain permission for microphone and/or camera usage, it was denied or it failed. Ensure to allow the permissions in the browser's and in the OS settings. ExpectedError Learn more about how to best handle device permissions.
40614 500 Failed to ask for device permissions Ensure to allow the permissions in the browser's settings and in the OS settings and try again. If issue persists, gather browser console logs and contact Azure Communication Services support. UnexpectedClientError Learn more about how to best handle device permissions.
41006 400 Failed to accept the incoming call, it isn't in the Ringing state. Subscribe to CallAgent's incomingCall event to accept the incoming call. ExpectedError Consult the following articles to identify the root cause of the issue
- Receive an incoming call
- Subscribe to SDK events
41007 400 Failed to reject the incoming call, it isn't in the Ringing state. Subscribe to CallAgent's incomingCall event to reject the incoming call. ExpectedError Consult the following articles to identify the root cause of the issue
- Receive an incoming call
- Subscribe to SDK events
41015 500 Failed to mute microphone. Try again, if the issue persists, gather browser console logs and contact Azure Communication Services support. UnexpectedClientError
41016 400 Failed to unmute microphone. Try again, if the issue persists, gather browser console logs and contact Azure Communication Services support. UnexpectedClientError
41025 400 Failed to start video, LocalVideoStream instance is invalid or empty. Pass in a LocalVideoStream instance. ExpectedError Make sure the object passed in to start video is an instance of LocalVideoStream.
Construct a LocalVideoStream using a VideoDeviceInfo object or a MediaStream object.

Consult the following articles to identify the root cause of the issue:
- Place a call with video camera
- Start and stop sending local video while on a call
- Access raw video
41027 400 Failed to start video, video is already started. ExpectedError Helpful links:
- Place a call with video camera
- Start and stop sending local video while on a call
41030 400 Failed to stop video, video is already stopped. ExpectedError Helpful links:
- Place a call with video camera
- Start and stop sending local video while on a call
41032 400 Failed to stop video, invalid argument. LocalVideoStream used as an input is currently not being sent. ExpectedError The LocalVideoStream that is being sent in the call, is stored in the Call.localVideoStreams[] array, and it's of type Video or RawMedia.
Consult the following articles to identify the root cause of the issue:
- Place a call with video camera
- Start and stop sending local video while on a call
- Access raw video
41033 500 Failed to hold the call. Try again, if the issue persists, gather browser console logs and contact Azure Communication Services support. UnexpectedClientError
41034 500 Failed to resume the call. Try again, if the issue persists, gather browser console logs and contact Azure Communication Services support. UnexpectedClientError
41035 400 Failed to start screen share, screen share is already started. ExpectedError Learn more about how to start and stop screen sharing while on a call
41041 400 Failed to stop screen share, screen share is already stopped. ExpectedError Learn more about how to start and stop screen sharing while on a call
41048 410 Failed to start video during call setup process. Ensure to allow video permissions in the browser's settings and in the OS settings, and ensure the camera device isn't being used by another process. UnexpectedClientError - The camera device might be disabled in the system.
- Camera is being used by another process.
41056 412 Failed to start or join to the call, Teams Enterprise voice policy isn't enabled for this Azure Communication Services resource. Follow the tutorial online to enable it. ExpectedError See on how to enable users for Enterprise Voice online and Phone System Voicemail to enable Teams Enterprise voice policy
41071 412 Failed to start screen share, call isn't in Connected state. Subscribe to the Call's statteChanged event to know when the call is connected. ExpectedError Helpful links:
- Check call properties
- Subscribe to SDK events
41073 412 Failed to get or set custom MediaStream, this functionality is currently disabled by Azure Communication Services. ExpectedError
43000 412 Failed to start video, video device is being used by another process/application. Stop your camera from being used in the other process/application and try again. ExpectedError Understand more about how to best deal with a camera being used by another process
43001 403 Failed to start video, permission wasn't granted to use selected video device. Ensure video device permissions are allowed in the browser's settings and in the system's settings. ExpectedError Ensure camera permissions are allowed in the browser settings and device system settings.
Ensure the cameras aren't disabled in the device system settings.
On macOS, ensure screen recording is allowed from the system settings.

Helpful links:
- Request device permissions-
Screen sharing permissions on macOS
- Enumerating or accessing devices for Safari on macOS and iOS
43002 500 Failed to start video, unknown error. Try again. If the issue persists, contact Azure Communication Services support. UnexpectedClientError
43004 400 Failed to switch video device, invalid input. Input must be of a VideoDeviceInfo type. ExpectedError Use the device manager to get a list of VideoDeviceInfo objects, and then use the VideoDeviceInfo object to switch the source.

Learn more on how to start and stop sending local video while on a call
43005 400 Failed to switch video device, unable to switch to the same video device, it's already selected. ExpectedError
43013 412 Failed to start video, no video devices found. Ensure video devices are plugged in and enabled in the system settings. ExpectedError Make sure you have a camera connected and installed on your device.
43014 412 Failed to start video, error requesting media stream. Try again, if issue persists, contact Azure Communication Services support. UnexpectedClientError
43015 412 Failed to start video, media stream request timed out. Allow permission on the browser's prompt to access the camera and try again. ExpectedError This error can occur if the user doesn't take action on the browser's permission prompt to allow access to the camera.
43016 412 Failed to start video, permissions denied by system. Ensure video device permissions are allowed in the browser's settings and in the system's settings. ExpectedError - Ensure camera permissions are allowed in the browser settings and device system settings.
- Ensure the cameras aren't disabled in the device system settings.
- On macOS, ensure screen recording is allowed from the system settings.

Helpful links:
- Request device permissions
-Screen sharing permissions on macOS
- Enumerating or accessing devices for Safari on macOS and iOS
43017 412 Failed to start video, unsupported stream. Try again, if issue persists, contact Azure Communication Services support. UnexpectedClientError
43018 412 Failed to start video, failed to set constraints. Try again, if issue persists, contact Azure Communication Services support. UnexpectedClientError Learn more about how to set video constraints
43019 412 Failed to start video, no device selected. Ensure to pass a LocalVideoStream constructed with a VideoDeviceInfo and try again. If issue persists, contact Azure Communication Services support. UnexpectedClientError Helpful links:
- Place a call with video camera
- Start and stop sending local video while on a call
43200 412 Failed to render video stream, this stream isn't available. Subscribe to the stream's isAvailable property to get notified when the remote participant has their video on and the stream is available for rendering. ExpectedError Helpful links:
- Render remote participant video/screensharing streams
- Add 1:1 video calling to your app
- Subscribe to SDK events
43202 404 Failed to render video stream, this stream isn't longer available. Remote participant turned off their video. ExpectedError The remote participant turned off their video while trying to create a view for it.
43203 408 Failed to render video stream, rendering timed out while waiting for video frames. Try again, if issue persists, contact Azure Communication Services support. UnexpectedClientError
43204 500 Failed to render video stream, failed to subscribe to video on the Azure Communication Services infrastructure. Try again, if issue persists, contact Azure Communication Services support. UnexpectedClientError
43209 405 Failed to render video stream, VideoStreamRenderer was disposed during initialization process. ExpectedError
43210 400 Failed to dispose VideoStreamRenderer because it's already disposed. ExpectedError
43220 400 Failed to create view, maximum number of active RemoteVideoStream views already reached. You can dispose of a previous one in order to create new one. ExpectedError Learn more about how to properly support the best number of incoming video streams
480 Remote client endpoint not registered. Ensure that the remote endpoint is available.
481 Failed to handle incoming call. File a support request through the Azure portal.
487 Call canceled, locally declined, ended due to an endpoint mismatch issue, or failed to generate media offer. Expected behavior.
490, 491, 496, 497, 498 Local endpoint network issues. Check your network.
503, 504 Communication Services infrastructure error. File a support request through the Azure portal.
600 Busy everywhere. Participant contacted successfully but returned busy signal. Expected behavior.
603 Call globally declined by remote Communication Services participant. Expected behavior.
604 Doesn't exist anywhere. Requested URI doesn't exist. Expected behavior.
606 Not acceptable. Participant successfully contacted but can't support the session described. Expected behavior.

Understanding calling codes and subcodes errors

Error codes, subcodes, and corresponding result categories help developers identify and diagnose errors. These error codes are exposed through the call.callEndReason property after a call ends.

Error code details include:

Code - are 3 digit integers representing client or server response status. The code categories:

  • Successful responses (200-299)
  • Client error (400-499)
  • Server error (500-599)
  • Global error (600-699)

Subcode - Are defined as an integer, where each number indicates a unique reason, specific to a group of scenarios or specific scenario outcome.

Message - Describes the outcome, and provides hints how to mitigate the problem if an outcome is a failure.

ResultCategory - Indicates the type of the error. Depending on the context, the value can be Success, ExpectedError, UnexpectedClientError, or UnexpectedServerError.

Calling End call codes and subcodes

There are different explanations for why a call ended. Here are the meanings of the end of call codes and subcodes that show how a call can end.

Subcode Code Message Result Categories Advice
0 0 Call ended successfully by local participant. Success
0 487 Call ended successfully as caller canceled the call. Success
0 603 Call ended successfully as it was declined from callee. Success Call ended because it was declined from the target user via either the client SDK, Call Automation, Graph, PSTN, or Teams reject function.
7 496 Call ended as client lost network connection abruptly, and despite retrying multiple times it wasn't able to connect ExpectedError Browser is offline or has network issues. Check your browser's network connection and retry.
3100 410 Call setup failed due to unexpected network problem on the client, check the client's network and retry. UnxpectedClientError Check network configuration, make sure it follows Azure Communication Calling network requirements.
3101 410 Call dropped due to unexpected network problem on the client, check the client's network and retry. UnxpectedClientError Check network configuration, make sure it follows Azure Communication Calling network requirements.
3111 410 Call setup failed, unable to process media offer while connecting the call. UnxpectedClientError Try again. If issue persists, gather call info, client logs, browser console logs and contact Azure Communication Services support.
3112 410 Call setup failed due to network configuration problem on the client side, check the client's network configuration, and retry. ExpectedError Learn more details about a call ending with a subcode of 3112 here.
4097 0 Call ended for all users by the meeting organizer. Success
4502 490 Call failed due to network connectivity problems, browser failed to complete the network HTTP request. UnexpectedClientError Client failed to complete HTTP request and response. Try again. If issue persists, gather call info, client logs, browser console logs and contact Azure Communication Services support.
4506 408 Call timed out. Check if the callee received and accepted the call. UnexpectedClientError Try again. If issue persists, gather call info, client logs, browser console logs and contact Azure Communication Services support.
4507 495 Call ended as application didn't provide valid Azure Communication Services token. UnexpectedClientError Ensure that your application implements token refresh mechanism correctly.
4521 0 Call ended because user disconnected from the call abruptly. This might be caused by a user closing the application that hosted the call, such as a user terminated the application by closing the browser tab without proper hang-up. ExpectedError
5000 0 Call ended for this participant. Participant removed from the conversation by another participant. Success
5003 0 Call ended successfully, as all callee endpoints declined the call. Success
5300 0 Call ended for this participant as it was removed from the conversation by another participant. Success Call ended for this participant as another participant removed it, it could be another client, Call Automation API, Graph API.
5317 0 Target participant is removed due to participant role update. ExpectedError
5828 403 The join isn't authorized for the Rooms meeting since user isn't part of invitee list. UnexpectedClientError
5829 403 The join isn't allowed for the Rooms meeting beyond end time or prior to start time of the meeting. UnexpectedClientError
5830 403 Only Communication Services user is allowed to join the Rooms meeting. ExpectedError
7000 0 Call was ended by Azure Communication Service Call Automation API or a server bot. Success Call was ended by ACS Call Automation API or Graph bot.
10003 487 Call was canceled for this user endpoint as it was accepted elsewhere, by another endpoint. Success A call was initiated to target user (start call, add participant, transfer), target user had multiple active endpoints at the same time, on one of the endpoints user accepted the call. This is normal behavior, only one endpoint can accept and connect to a call. All other endpoints receive subcode 10003 to indicate that call was already accepted.
10004 487 Call was canceled on timeout, as target user didn't accept or reject it on time. Ensure that user saw the notification and/or application can handle it automatically and try to initiate that call again. ExpectedError Call was canceled after predefined amount of time (usually 2 minutes) as target user didn't accept or reject.
10009 401 Unauthenticated identity. Ensure that your Azure Communication Services token is valid and not expired. UnexpectedClientError
10024 487 Call ended successfully. Call declined by all callee endpoints. Success Try to place the call again.
10037 480 Target user didn't have any endpoints registered with ACS. Ensure that target user has at least one active endpoint and it's online. ExpectedError If the target user is using the Azure Communication Services Calling SDK, ensure that the SDK is initialized successfully in their client application. If the target user is a Teams user, make sure that their client is online. Make sure that the target user's identifier (CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier, or MicrosoftTeamsBotIdentifier) is correct. If the Graph API user has property department set to Microsoft Communication Application Instance the MicrosoftTeamsBotIdentifier should be specified.
10057 408 Call failed, callee failed to finalize call setup, most likely callee lost network or terminated the application abruptly. Ensure clients are connected and available. ExpectedError
10076 480 Target user was registered but it wasn't online at the time of the call. Ensure that target user has at least one active endpoint and it's online. ExpectedError If the target user is using the Azure Communication Services Calling SDK, ensure that the SDK is initialized successfully in their client application and their endpoint is online. If the target user is a Teams user, make sure that their client is online.
10077 480 Target user was registered with ACS and/or for push notifications, but it wasn't online at the time of the call. Ensure that target user has at least one active endpoint and it's online. ExpectedError If the target user is using the Azure Communication Services Calling SDK, ensure that the SDK is initialized successfully in their client application and their endpoint is online. If application leverages Push Notifications make sure they're configured correctly. If the target user is a Teams user, make sure that their client is online.
10078 480 Remote client endpoint not registered or not reachable. Ensure the remote client endpoint is successfully sending network requests to Azure Communication Services. ExpectedError - If the target user is using the Azure Communication Services Calling SDK, ensure that the SDK is initialized successfully in their client application and their endpoint is online. If application leverages Push Notifications make sure they're configured correctly.
- If the target user is a Teams user, make sure that their client is online.
301004 410 Participant was removed from the call by the Azure Communication Services infrastructure due to inability to establish media connectivity with Azure Communication Services infrastructure during call setup. Check user's network configuration, including local network, firewalls, VPNs configuration and try again. UnexpectedClientError Ensure that user's network is configured correctly, follow 'Network Recommendations' public documentation.
301005 410 Participant removed from the call by the Azure Communication Services infrastructure due to loss of media connectivity with the same infrastructure. This usually happens if participant leaves the call abruptly or loses network connectivity. If the participant wants to continue the call, they can reconnect. UnexpectedClientError Ensure that you're using the latest SDK in a supported environment.
540000 0 Call ended successfully by local PSTN caller. Success
510403 403 Call ended, previously marked as a spam and now blocked. ExpectedError - Ensure that your Communication Services token is valid and not expired.
- Ensure to pass in AlternateId in the call options.
540487 487 Call ended successfully as caller canceled the call. Success
560000 0 Call ended successfully by remote PSTN participant. Success Possible causes:
- User ended the call.
- Call ended by media agent.
560486 486 Call ended because remote PSTN participant was busy. The number called was already in a call or having technical issues. Success - For Direct Routing calls, check your Session Border Control logs and settings and timeouts configuration. Possible causes: The number called was already in a call or having technical issues.
404 Call not found. Ensure that the number you're calling (or call you're joining) exists.
408 Call controller timed out. Call Controller timed out waiting for protocol messages from user endpoints. Ensure clients are connected and available.
410 Local media stack or media infrastructure error. Ensure that you're using the latest SDK in a supported environment.
430 Unable to deliver message to client application. Ensure that the client application is running and available.
480 Remote client endpoint not registered. Ensure that the remote endpoint is available.
481 Failed to handle incoming call. File a support request through the Azure portal.
490, 491, 496, 497, 498 Local endpoint network issues. Check network configuration, make sure it follows Azure Communication Calling network requirements.
500, 503, 504 Communication Services infrastructure error. File a support request through the Azure portal.