Bluetooth ATT & HCI Error Decoder

Bluetooth error values are one-byte numbers, but they do not share one global namespace. The same value can identify different failures at different layers. For example, 0x05 is Insufficient Authentication in ATT and Authentication Failure in the Controller error table.

Use ATT when the value comes from an ATT Error Response during a GATT read, write, subscription, or discovery procedure. Use HCI / Controller when it appears in a command result, connection-complete event, or disconnection reason.

ATT errors describe why an attribute request could not be completed. Permission errors such as Read Not Permitted are distinct from security errors such as Insufficient Authentication and Insufficient Encryption. Database Out Of Sync tells a robust-caching client to invalidate its cached view and rediscover the GATT database.

Values 0x80–0x9F are defined by higher-layer profiles, services, or applications. Common profile and service errors occupy the upper range, including Procedure Already in Progress 0xFE and Out of Range 0xFF. Their exact use still depends on the service procedure that returned them.

References: Bluetooth Core ATT specification and Common Profile and Service Error Codes.

HCI status values report failures observed by the Host Controller Interface and lower layers. A code can describe command validation, Controller capacity, security, connection establishment, link loss, or an intentional disconnect.

Preserve the event name and command opcode with the code. Connection Timeout 0x08 on a disconnection event points toward link supervision or synchronization loss, while Command Disallowed 0x0C is meaningful only alongside the command and the Controller state in which it was issued.

Reference: Bluetooth Core Controller Error Codes.

• Record the protocol layer, event or operation, and timestamp.
• Keep the connection handle, attribute handle, command opcode, and peer role where available.
• Inspect the events immediately before the failure; many status values describe the outcome, not the initiating cause.
• Compare negotiated security, connection parameters, and supported features before changing retry behavior.
• Treat repeated resource, timing, and unspecified errors as a reason to capture Controller and firmware diagnostics rather than add unbounded retries.