Result Code - IoT SDK

Every SDK call returns a result_t. RESULT_OK (0) means the operation succeeded; anything else tells you what went wrong and, in most cases, what to do about it. On a device there is no exception to catch and no user watching, so check the return of every call and log it.

result_t r = startPublishAudio();
if (r != RESULT_OK) {
  ESP_LOGE("IOT-SDK", "startPublishAudio failed: %d", r);
}

How to read a failure

Codes fall into a few groups, and each group wants a different response.

• Expected on this hardware. DEVICE_NOT_SUPPORTED (3004) from a subscribe call means the board has no speaker or no display. Not a failure, and retrying will not change it. See Supported Microcontrollers.
• Wrong call order. INIT_NOT_CALLED (3023), DATA_CHANNEL_NOT_STARTED (3025) and TASK_ALREADY_STARTED (3008) are programming errors. Fix the sequence rather than retrying.
• Out of memory. The allocation, mutex and task-creation codes mean the device ran short of RAM. Check what is actually free before you retry. See Logging and Debugging.
• Network and transport. SSL_CONNECT_FAILED (3001), CANDIDATE_PAIR_FAILED (3020) and DTLS_HANDSHAKE_FAILED (3021) mean the device could not reach or negotiate with the server. Retry with backoff, and suspect the network itself if they persist.
• Session already gone. If the session dropped mid-call, rejoin instead of retrying the call that failed. See Connection State.

caution

leave() is the one call whose failures need opposite responses. STOP_PUBLISH_TASK_CREATE_FAILED (3018) and STOP_SUBSCRIBE_TASK_CREATE_FAILED (3019) mean teardown never started and the session is still up, so call leave() again. LEAVE_FAILED (3022) means teardown got stuck, so do not treat it as a clean exit.

All result codes

Enum Constant	Value	Description
RESULT_OK	0	Operation completed successfully with no errors.
SSL_CONNECT_FAILED	3001	The TLS handshake with the VideoSDK server did not complete. Confirm the device has working DNS and internet access, and that CONFIG_MBEDTLS_CERTIFICATE_BUNDLE and CONFIG_MBEDTLS_CERTIFICATE_BUNDLE_DEFAULT_FULL are still set in your sdkconfig, since a trimmed bundle cannot verify the server certificate. Retry once the network is up.
HTTP_REQUEST_FAILED	3002	The HTTP request could not be sent from the device, or the server did not respond. Check that Wi-Fi is connected and DNS resolves, and that the token is not empty. Retry with a delay rather than in a tight loop.
MEMORY_ALLOC_FAILED	3003	Allocation failed because the requested buffer exceeded the available heap. Confirm PSRAM is enabled (CONFIG_SPIRAM, CONFIG_SPIRAM_MODE_OCT, CONFIG_SPIRAM_SPEED_80M), print the free heap, and reduce your own allocations before retrying. See Logging and Debugging.
DEVICE_NOT_SUPPORTED	3004	The board does not have the hardware for that direction: receiving audio needs a speaker and receiving video needs a display. The subscribe calls return this code on boards without that hardware (expected, not a failure). See Supported Microcontrollers.
NULL_PARAMETER	3005	A function call failed because a required input parameter was NULL or empty, resulting in an invalid operation. Ensure all required parameters are properly initialized before invoking the function.
INIT_BOARD_FAILED	3006	Initialization of the board or audio codec hardware failed. Check that the board selected under menuconfig -> SET Microcontroller matches the hardware you are flashing, and that the board is powered and seated correctly.
PEER_INIT_FAILED	3007	SRTP initialization failed, usually a memory shortage or a stale build. Print the free heap, then rebuild after deleting sdkconfig, and confirm the libsrtp compile option from Quick Start, Step 3, is present in main/CMakeLists.txt.
TASK_ALREADY_STARTED	3008	That direction is already running. There is no separate stop call, so end the session with leave() before starting it again.
PUBLISH_MUTEX_CREATE_FAILED	3009	The mutex needed to synchronize publishing could not be allocated. Free memory and retry. See Logging and Debugging.
AUDIO_CODEC_INIT_FAILED	3010	Audio codec initialization failed, usually a codec the board cannot handle. Select a different init_config_t.audioCodec (AUDIO_CODEC_PCMA, AUDIO_CODEC_PCMU or AUDIO_CODEC_OPUS) and confirm your board selection under menuconfig -> SET Microcontroller.
PUBLISH_PEER_CONNECTION_FAILED	3011	The peer connection for publishing failed to come up. Verify the token is valid and unexpired, that the meeting ID exists, and that the network allows outbound UDP. Retry with backoff.
PUBLISH_MEMORY_ALLOC_FAILED	3012	Memory for the publishing path could not be allocated. Confirm PSRAM is enabled and check the free heap before retrying. See Logging and Debugging.
PUBLISH_TASK_CREATE_FAILED	3013	FreeRTOS could not create the publishing task, usually because internal RAM is exhausted. Free memory, or allow task stacks in PSRAM with CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY, then retry.
SUBSCRIBE_MUTEX_CREATE_FAILED	3014	The mutex needed to synchronize subscribing could not be allocated. Free memory and retry. See Logging and Debugging.
SUBSCRIBE_PEER_CONNECTION_FAILED	3015	The peer connection for subscribing failed to come up. Verify the token is valid and unexpired, that the meeting ID exists, and that the network allows outbound UDP. Retry with backoff.
SUBSCRIBE_MEMORY_ALLOC_FAILED	3016	Memory for the subscribing path could not be allocated. Confirm PSRAM is enabled and check the free heap before retrying. See Logging and Debugging.
SUBSCRIBE_TASK_CREATE_FAILED	3017	FreeRTOS could not create the subscribing task, usually because internal RAM is exhausted. Free memory, or allow task stacks in PSRAM with CONFIG_SPIRAM_ALLOW_STACK_EXTERNAL_MEMORY, then retry.
STOP_PUBLISH_TASK_CREATE_FAILED	3018	leave() could not start tearing down the publishing side, so nothing was torn down and the session is still active. Free some memory and call leave() again.
STOP_SUBSCRIBE_TASK_CREATE_FAILED	3019	leave() could not start tearing down the subscribing side, so nothing was torn down and the session is still active. Free some memory and call leave() again.
CANDIDATE_PAIR_FAILED	3020	ICE found no working network path. Usually a network that blocks outbound UDP, such as guest Wi-Fi or a captive portal. Try another network or a phone hotspot to confirm, then retry the join.
DTLS_HANDSHAKE_FAILED	3021	The DTLS handshake between peers failed. Retry the join. If it repeats, check the free heap and that the CONFIG_MBEDTLS_* options from Quick Start, Step 5, are still set, and make sure only one session is active on the device.
LEAVE_FAILED	3022	Teardown started but did not finish within 6 seconds, so something is stuck. Unlike 3018/3019, the session is not left intact, so do not assume it is safe to rejoin immediately.
INIT_NOT_CALLED	3023	This error occurs when the init() function was not called before using other functions like publish() or subscribe(). To resolve this, call init() first.
DATA_CHANNEL_NOT_STARTED	3025	sendMessage() was called before startMessageChannel(). Call startMessageChannel() once before sending messages.
DATA_CHANNEL_QUEUE_FULL	3026	The message send queue is momentarily full, so the message was not queued. Retry shortly.