NimBLE Host Return Codes

Introduction

Summary

The NimBLE host reports status to the application via a set of return codes. The host encompasses several layers of the Bluetooth specification that each defines its own set of status codes. Rather than “abstract away” information from lower layers that the application developer might find useful, the NimBLE host aims to indicate precisely what happened when something fails. Consequently, the host utilizes a rather large set of return codes.

A return code of 0 indicates success. For failure conditions, the return codes are partitioned into five separate sets:

Set	Condition
Core	Errors detected internally by the NimBLE host.
ATT	The ATT server has reported a failure via the transmission of an ATT Error Response. The return code corresponds to the value of the Error Code field in the response.
HCI	The controller has reported an error to the host via a command complete or command status HCI event. The return code corresponds to the value of the Status field in the event.
L2CAP	An L2CAP signaling procedure has failed and an L2CAP Command Reject was sent as a result. The return code corresponds to the value of the Reason field in the command.
Security manager (us)	The host detected an error during a security manager procedure and sent a Pairing Failed command to the peer. The return code corresponds to the value of the Reason field in the Pairing Failed command.
Security manager (peer)	A security manager procedure failed because the peer sent us a Pairing Failed command. The return code corresponds to the value of the Reason field in the Pairing Failed command.

The return codes in the core set are defined by the NimBLE Host. The other sets are defined in the Bluetooth specification; the codes in this latter group are referred to as formal status codes. As defined in the Bluetooth specification, the formal status code sets are not disjoint. That is, they overlap. For example, the spec defines a status code of 1 to have all of the following meanings:

Layer	Meaning
ATT	Invalid handle.
HCI	Unknown HCI command.
L2CAP	Signalling MTU exceeded.
SM	Passkey entry failed.

Clearly, the host can’t just return an unadorned formal status code and expect the application to make sense of it. To resolve this ambiguity, the NimBLE host divides the full range of an int into several subranges. Each subrange corresponds to one of the five return code sets. For example, the ATT set is mapped onto the subrange [0x100, 0x200). To indicate an ATT error of 3 (write not permitted), the NimBLE host returns a value 0x103 to the application.

The host defines a set of convenience macros for converting from a formal status code to NimBLE host status code. These macros are documented in the table below.

Macro	Status code set	Base value
BLE_HS_ATT_ERR()	ATT	0x100
BLE_HS_HCI_ERR()	HCI	0x200
BLE_HS_L2C_ERR()	L2CAP	0x300
BLE_HS_SM_US_ERR()	Security manager (us)	0x400
BLE_HS_SM_PEER_ERR()	Security manager (peer)	0x500

Example

The following example demonstrates how an application might determine which error is being reported by the host. In this example, the application performs the GAP encryption procedure and checks the return code. To simplify the example, the application uses a hypothetical my_blocking_enc_proc() function, which blocks until the pairing operation has completed.

void
encrypt_connection(uint16_t conn_handle)
{
    int rc;

    /* Perform a blocking GAP encryption procedure. */
    rc = my_blocking_enc_proc(conn_handle);
    switch (rc) {
    case 0:
        console_printf("success - link successfully encrypted\n");
        break;

    case BLE_HS_ENOTCONN:
        console_printf("failure - no connection with handle %d\n",
                       conn_handle);
        break;

    case BLE_HS_ERR_SM_US_BASE(BLE_SM_ERR_CONFIRM_MISMATCH):
        console_printf("failure - mismatch in peer's confirm and random "
                       "commands.\n");
        break;

    case BLE_HS_ERR_SM_PEER_BASE(BLE_SM_ERR_CONFIRM_MISMATCH):
        console_printf("failure - peer reports mismatch in our confirm and "
                       "random commands.\n");
        break;

    default:
        console_printf("failure - other error: 0x%04x\n", rc);
        break;
    }
}

Return Code Reference

Header

All NimBLE host return codes are made accessible by including the following header:

#include "host/ble_hs.h"

Return codes - Core

The precise meaning of each of these error codes depends on the function that returns it. The API reference for a particular function indicates the conditions under which each of these codes are returned.

Value	Name	Condition
0x00	N/A	Success
0x01	BLE_HS_EAGAIN	Temporary failure; try again.
0x02	BLE_HS_EALREADY	Operation already in progress or completed.
0x03	BLE_HS_EINVAL	One or more arguments are invalid.
0x04	BLE_HS_EMSGSIZE	The provided buffer is too small.
0x05	BLE_HS_ENOENT	No entry matching the specified criteria.
0x06	BLE_HS_ENOMEM	Operation failed due to resource exhaustion.
0x07	BLE_HS_ENOTCONN	No open connection with the specified handle.
0x08	BLE_HS_ENOTSUP	Operation disabled at compile time.
0x09	BLE_HS_EAPP	Application callback behaved unexpectedly.
0x0a	BLE_HS_EBADDATA	Command from peer is invalid.
0x0b	BLE_HS_EOS	Mynewt OS error.
0x0c	BLE_HS_ECONTROLLER	Event from controller is invalid.
0x0d	BLE_HS_ETIMEOUT	Operation timed out.
0x0e	BLE_HS_EDONE	Operation completed successfully.
0x0f	BLE_HS_EBUSY	Operation cannot be performed until procedure completes.
0x10	BLE_HS_EREJECT	Peer rejected a connection parameter update request.
0x11	BLE_HS_EUNKNOWN	Unexpected failure; catch all.
0x12	BLE_HS_EROLE	Operation requires different role (e.g., central vs. peripheral).
0x13	BLE_HS_ETIMEOUT_HCI	HCI request timed out; controller unresponsive.
0x14	BLE_HS_ENOMEM_EVT	Controller failed to send event due to memory exhaustion (combined host-controller only).
0x15	BLE_HS_ENOADDR	Operation requires an identity address but none configured.
0x16	BLE_HS_ENOTSYNCED	Attempt to use the host before it is synced with controller.
0x17	BLE_HS_EAUTHEN	Insufficient authentication.
0x18	BLE_HS_EAUTHOR	Insufficient authorization.
0x19	BLE_HS_EENCRYPT	Insufficient encryption level.
0x1a	BLE_HS_EENCRYPT_KEY_SZ	Insufficient key size.
0x1b	BLE_HS_ESTORE_CAP	Storage at capacity.
0x1c	BLE_HS_ESTORE_FAIL	Storage IO error.

Return codes - ATT

NimBLE Value	Formal Value	Name	Condition
0x0101	0x01	BLE_ATT_ERR_INVALID_HANDLE	The attribute handle given was not valid on this server.
0x0102	0x02	BLE_ATT_ERR_READ_NOT_PERMITTED	The attribute cannot be read.
0x0103	0x03	BLE_ATT_ERR_WRITE_NOT_PERMITTED	The attribute cannot be written.
0x0104	0x04	BLE_ATT_ERR_INVALID_PDU	The attribute PDU was invalid.
0x0105	0x05	BLE_ATT_ERR_INSUFFICIENT_AUTHEN	The attribute requires authentication before it can be read or written.
0x0106	0x06	BLE_ATT_ERR_REQ_NOT_SUPPORTED	Attribute server does not support the request received from the client.
0x0107	0x07	BLE_ATT_ERR_INVALID_OFFSET	Offset specified was past the end of the attribute.
0x0108	0x08	BLE_ATT_ERR_INSUFFICIENT_AUTHOR	The attribute requires authorization before it can be read or written.
0x0109	0x09	BLE_ATT_ERR_PREPARE_QUEUE_FULL	Too many prepare writes have been queued.
0x010a	0x0a	BLE_ATT_ERR_ATTR_NOT_FOUND	No attribute found within the given attribute handle range.
0x010b	0x0b	BLE_ATT_ERR_ATTR_NOT_LONG	The attribute cannot be read or written using the Read Blob Request.
0x010c	0x0c	BLE_ATT_ERR_INSUFFICIENT_KEY_SZ	The Encryption Key Size used for encrypting this link is insufficient.
0x010d	0x0d	BLE_ATT_ERR_INVALID_ATTR_VALUE_LEN	The attribute value length is invalid for the operation.
0x010e	0x0e	BLE_ATT_ERR_UNLIKELY	The attribute request that was requested has encountered an error that was unlikely, and therefore could not be completed as requested.
0x010f	0x0f	BLE_ATT_ERR_INSUFFICIENT_ENC	The attribute requires encryption before it can be read or written.
0x0110	0x10	BLE_ATT_ERR_UNSUPPORTED_GROUP	The attribute type is not a supported grouping attribute as defined by a higher layer specification.
0x0111	0x11	BLE_ATT_ERR_INSUFFICIENT_RES	Insufficient Resources to complete the request.

Return codes - HCI

NimBLE Value	Formal Value	Name	Condition
0x0201	0x01	BLE_ERR_UNKNOWN_HCI_CMD	Unknown HCI Command
0x0202	0x02	BLE_ERR_UNK_CONN_ID	Unknown Connection Identifier
0x0203	0x03	BLE_ERR_HW_FAIL	Hardware Failure
0x0204	0x04	BLE_ERR_PAGE_TMO	Page Timeout
0x0205	0x05	BLE_ERR_AUTH_FAIL	Authentication Failure
0x0206	0x06	BLE_ERR_PINKEY_MISSING	PIN or Key Missing
0x0207	0x07	BLE_ERR_MEM_CAPACITY	Memory Capacity Exceeded
0x0208	0x08	BLE_ERR_CONN_SPVN_TMO	Connection Timeout
0x0209	0x09	BLE_ERR_CONN_LIMIT	Connection Limit Exceeded
0x020a	0x0a	BLE_ERR_SYNCH_CONN_LIMIT	Synchronous Connection Limit To A Device Exceeded
0x020b	0x0b	BLE_ERR_ACL_CONN_EXISTS	ACL Connection Already Exists
0x020c	0x0c	BLE_ERR_CMD_DISALLOWED	Command Disallowed
0x020d	0x0d	BLE_ERR_CONN_REJ_RESOURCES	Connection Rejected due to Limited Resources
0x020e	0x0e	BLE_ERR_CONN_REJ_SECURITY	Connection Rejected Due To Security Reasons
0x020f	0x0f	BLE_ERR_CONN_REJ_BD_ADDR	Connection Rejected due to Unacceptable BD_ADDR
0x0210	0x10	BLE_ERR_CONN_ACCEPT_TMO	Connection Accept Timeout Exceeded
0x0211	0x11	BLE_ERR_UNSUPPORTED	Unsupported Feature or Parameter Value
0x0212	0x12	BLE_ERR_INV_HCI_CMD_PARMS	Invalid HCI Command Parameters
0x0213	0x13	BLE_ERR_REM_USER_CONN_TERM	Remote User Terminated Connection
0x0214	0x14	BLE_ERR_RD_CONN_TERM_RESRCS	Remote Device Terminated Connection due to Low Resources
0x0215	0x15	BLE_ERR_RD_CONN_TERM_PWROFF	Remote Device Terminated Connection due to Power Off
0x0216	0x16	BLE_ERR_CONN_TERM_LOCAL	Connection Terminated By Local Host
0x0217	0x17	BLE_ERR_REPEATED_ATTEMPTS	Repeated Attempts
0x0218	0x18	BLE_ERR_NO_PAIRING	Pairing Not Allowed
0x0219	0x19	BLE_ERR_UNK_LMP	Unknown LMP PDU
0x021a	0x1a	BLE_ERR_UNSUPP_REM_FEATURE	Unsupported Remote Feature / Unsupported LMP Feature
0x021b	0x1b	BLE_ERR_SCO_OFFSET	SCO Offset Rejected
0x021c	0x1c	BLE_ERR_SCO_ITVL	SCO Interval Rejected
0x021d	0x1d	BLE_ERR_SCO_AIR_MODE	SCO Air Mode Rejected
0x021e	0x1e	BLE_ERR_INV_LMP_LL_PARM	Invalid LMP Parameters / Invalid LL Parameters
0x021f	0x1f	BLE_ERR_UNSPECIFIED	Unspecified Error
0x0220	0x20	BLE_ERR_UNSUPP_LMP_LL_PARM	Unsupported LMP Parameter Value / Unsupported LL Parameter Value
0x0221	0x21	BLE_ERR_NO_ROLE_CHANGE	Role Change Not Allowed
0x0222	0x22	BLE_ERR_LMP_LL_RSP_TMO	LMP Response Timeout / LL Response Timeout
0x0223	0x23	BLE_ERR_LMP_COLLISION	LMP Error Transaction Collision
0x0224	0x24	BLE_ERR_LMP_PDU	LMP PDU Not Allowed
0x0225	0x25	BLE_ERR_ENCRYPTION_MODE	Encryption Mode Not Acceptable
0x0226	0x26	BLE_ERR_LINK_KEY_CHANGE	Link Key cannot be Changed
0x0227	0x27	BLE_ERR_UNSUPP_QOS	Requested QoS Not Supported
0x0228	0x28	BLE_ERR_INSTANT_PASSED	Instant Passed
0x0229	0x29	BLE_ERR_UNIT_KEY_PAIRING	Pairing With Unit Key Not Supported
0x022a	0x2a	BLE_ERR_DIFF_TRANS_COLL	Different Transaction Collision
0x022c	0x2c	BLE_ERR_QOS_PARM	QoS Unacceptable Parameter
0x022d	0x2d	BLE_ERR_QOS_REJECTED	QoS Rejected
0x022e	0x2e	BLE_ERR_CHAN_CLASS	Channel Classification Not Supported
0x022f	0x2f	BLE_ERR_INSUFFICIENT_SEC	Insufficient Security
0x0230	0x30	BLE_ERR_PARM_OUT_OF_RANGE	Parameter Out Of Mandatory Range
0x0232	0x32	BLE_ERR_PENDING_ROLE_SW	Role Switch Pending
0x0234	0x34	BLE_ERR_RESERVED_SLOT	Reserved Slot Violation
0x0235	0x35	BLE_ERR_ROLE_SW_FAIL	Role Switch Failed
0x0236	0x36	BLE_ERR_INQ_RSP_TOO_BIG	Extended Inquiry Response Too Large
0x0237	0x37	BLE_ERR_SEC_SIMPLE_PAIR	Secure Simple Pairing Not Supported By Host
0x0238	0x38	BLE_ERR_HOST_BUSY_PAIR	Host Busy - Pairing
0x0239	0x39	BLE_ERR_CONN_REJ_CHANNEL	Connection Rejected due to No Suitable Channel Found
0x023a	0x3a	BLE_ERR_CTLR_BUSY	Controller Busy
0x023b	0x3b	BLE_ERR_CONN_PARMS	Unacceptable Connection Parameters
0x023c	0x3c	BLE_ERR_DIR_ADV_TMO	Directed Advertising Timeout
0x023d	0x3d	BLE_ERR_CONN_TERM_MIC	Connection Terminated due to MIC Failure
0x023e	0x3e	BLE_ERR_CONN_ESTABLISHMENT	Connection Failed to be Established
0x023f	0x3f	BLE_ERR_MAC_CONN_FAIL	MAC Connection Failed
0x0240	0x40	BLE_ERR_COARSE_CLK_ADJ	Coarse Clock Adjustment Rejected but Will Try to Adjust Using Clock Dragging

Return codes - L2CAP

NimBLE Value	Formal Value	Name	Condition
0x0300	0x00	BLE_L2CAP_SIG_ERR_CMD_NOT_UNDERSTOOD	Invalid or unsupported incoming L2CAP sig command.
0x0301	0x01	BLE_L2CAP_SIG_ERR_MTU_EXCEEDED	Incoming packet too large.
0x0302	0x02	BLE_L2CAP_SIG_ERR_INVALID_CID	No channel with specified ID.

Return codes - Security manager (us)

NimBLE Value	Formal Value	Name	Condition
0x0401	0x01	BLE_SM_ERR_PASSKEY	The user input of passkey failed, for example, the user cancelled the operation.
0x0402	0x02	BLE_SM_ERR_OOB	The OOB data is not available.
0x0403	0x03	BLE_SM_ERR_AUTHREQ	The pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices.
0x0404	0x04	BLE_SM_ERR_CONFIRM_MISMATCH	The confirm value does not match the calculated compare value.
0x0405	0x05	BLE_SM_ERR_PAIR_NOT_SUPP	Pairing is not supported by the device.
0x0406	0x06	BLE_SM_ERR_ENC_KEY_SZ	The resultant encryption key size is insufficient for the security requirements of this device.
0x0407	0x07	BLE_SM_ERR_CMD_NOT_SUPP	The SMP command received is not supported on this device.
0x0408	0x08	BLE_SM_ERR_UNSPECIFIED	Pairing failed due to an unspecified reason.
0x0409	0x09	BLE_SM_ERR_REPEATED	Pairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request.
0x040a	0x0a	BLE_SM_ERR_INVAL	The Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range.
0x040b	0x0b	BLE_SM_ERR_DHKEY	Indicates to the remote device that the DHKey Check value received doesn’t match the one calculated by the local device.
0x040c	0x0c	BLE_SM_ERR_NUMCMP	Indicates that the confirm values in the numeric comparison protocol do not match.
0x040d	0x0d	BLE_SM_ERR_ALREADY	Indicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process.
0x040e	0x0e	BLE_SM_ERR_CROSS_TRANS	Indicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.

Return codes - Security manager (peer)

NimBLE Value	Formal Value	Name	Condition
0x0501	0x01	BLE_SM_ERR_PASSKEY	The user input of passkey failed, for example, the user cancelled the operation.
0x0502	0x02	BLE_SM_ERR_OOB	The OOB data is not available.
0x0503	0x03	BLE_SM_ERR_AUTHREQ	The pairing procedure cannot be performed as authentication requirements cannot be met due to IO capabilities of one or both devices.
0x0504	0x04	BLE_SM_ERR_CONFIRM_MISMATCH	The confirm value does not match the calculated compare value.
0x0505	0x05	BLE_SM_ERR_PAIR_NOT_SUPP	Pairing is not supported by the device.
0x0506	0x06	BLE_SM_ERR_ENC_KEY_SZ	The resultant encryption key size is insufficient for the security requirements of this device.
0x0507	0x07	BLE_SM_ERR_CMD_NOT_SUPP	The SMP command received is not supported on this device.
0x0508	0x08	BLE_SM_ERR_UNSPECIFIED	Pairing failed due to an unspecified reason.
0x0509	0x09	BLE_SM_ERR_REPEATED	Pairing or authentication procedure is disallowed because too little time has elapsed since last pairing request or security request.
0x050a	0x0a	BLE_SM_ERR_INVAL	The Invalid Parameters error code indicates that the command length is invalid or that a parameter is outside of the specified range.
0x050b	0x0b	BLE_SM_ERR_DHKEY	Indicates to the remote device that the DHKey Check value received doesn’t match the one calculated by the local device.
0x050c	0x0c	BLE_SM_ERR_NUMCMP	Indicates that the confirm values in the numeric comparison protocol do not match.
0x050d	0x0d	BLE_SM_ERR_ALREADY	Indicates that the pairing over the LE transport failed due to a Pairing Request sent over the BR/EDR transport in process.
0x050e	0x0e	BLE_SM_ERR_CROSS_TRANS	Indicates that the BR/EDR Link Key generated on the BR/EDR transport cannot be used to derive and distribute keys for the LE transport.