BLE ATT Error Responses: Separate Permissions, Authentication and Value Errors
Preserve the ATT failure before translating it
“Bluetooth write failed” is too broad to guide either a developer or a user. The operation may have been rejected locally by a phone API, timed out on the link, or reached the server and received an ATT Error Response. Preserve that distinction first. This guide uses Bluetooth Core 6.0, Volume 3, Part F as its protocol baseline. It covers error interpretation and recovery decisions rather than GATT database design or notification throughput. A platform callback number is not automatically an ATT error code; record its namespace and map it only through the platform’s documented API. When the stack hides the protocol detail, report that visibility limit instead of assigning an invented ATT cause. For qualification, consult the SIG’s Core 6.0 page and mandatory updates; this engineering guide is not a compliance checklist.
Decode the response with the operation context
The Core 6.0 ATT specification defines an Error Response containing the failed request opcode, the attribute handle in error and an error code. As a constructed parser fixture, the bytes 01 12 25 00 0D describe an Error Response for Write Request 0x12, handle 0x0025 and Invalid Attribute Value Length 0x0D. This is not a captured device trace. The handle is a database address, so retain the discovered characteristic identity and database context with it. A stale or incorrectly mapped handle can make a real response look like a value-format issue on the wrong characteristic. Log transaction identity and intended operation without dumping the characteristic value if it contains user data.
Separate operation permission from security requirements
Read Not Permitted 0x02 and Write Not Permitted 0x03 indicate that the requested access is not allowed for the attribute. Insufficient Authentication 0x05, Insufficient Authorization 0x08 and Insufficient Encryption 0x0F describe different access prerequisites. Encryption Key Size Too Short 0x0C adds a distinct security constraint. Do not collapse all of these into “pair again.” Authentication concerns security properties; authorization concerns permission to perform the action and may depend on application policy. Nordic’s services-and-characteristics explanation also separates attribute permissions from characteristic structure. A readable value need not be writable, and a characteristic declaration’s advertised properties do not replace the server’s access checks on the value.
Choose the next action from the cause
For a permission mismatch, verify that the client selected the correct characteristic and operation; repeated identical requests will not fix a read-only value. For an unmet security requirement, let the platform’s supported security flow run and retry only after a confirmed relevant state change. An authorization denial may need an owner action or a different authenticated application session, not another radio pairing. A too-short encryption key cannot be fixed by resending the same value. Preserve the required security policy rather than weakening the server to make a test pass. Put an explicit bound on any retry sequence so the user is not trapped in repeated permission prompts or automatic disconnect-and-reconnect loops.
Interpret length and offset in their procedure
Invalid Offset 0x07 means the requested offset is beyond the permitted value boundary in the applicable procedure. For a Read Blob operation, Core 6.0 distinguishes an offset beyond the current value from an offset equal to its length, which returns an empty part. Invalid Attribute Value Length 0x0D concerns an unacceptable value length; it is not synonymous with a small negotiated ATT MTU. Check the characteristic’s application format, the selected write procedure and the negotiated limits separately. Attribute Not Found 0x0A can also be the expected termination of a discovery search, rather than a device failure. A parser must interpret the code in the context of the outstanding request, not through a global error-to-toast dictionary.
Remember which operations can return an error
An ATT Write Command has no ATT response, so a successful local enqueue does not prove that the server accepted the value. The same specification requires unsupported commands to be ignored rather than answered with an Error Response. Notifications likewise do not provide an application-level acknowledgment. When a critical operation needs a reviewable outcome, choose a request/response path where appropriate and define an application acknowledgment for the consequential business action. Do not wait forever for a protocol error that the chosen operation cannot send. Keep the transport acceptance, ATT result and application commit as separate states, particularly when a command changes a configuration that must survive reboot.
Inject one error condition at a time
Use a controlled test server with a fixed attribute map. Exercise a read on a non-readable value, a write on a non-writable value, an unmet authentication condition, an application authorization denial, insufficient encryption, an invalid length and an out-of-range offset. Use deliberately synthetic values and capture the request context as well as the result. Then repeat each case after the intended prerequisite is satisfied, without changing unrelated server permissions. Add an ordinary discovery end condition and a Write Command rejection to ensure the client does not mistake silence for success or failure. This is a proposed test matrix; no phone, server or over-the-air test was performed for this guide.
Ship useful messages and bounded recovery
Acceptance requires that protocol errors, platform API failures and timeouts remain distinguishable in diagnostics. Show users an actionable summary such as “this operation needs owner authorization” or “the value has an unsupported length,” while retaining the precise code for support. Do not expose raw sensitive values. Verify that a corrected request can proceed without clearing unrelated state, and that permanent failures stop retrying. Version the error mapping with both the mobile API and embedded stack. A good error model preserves enough protocol context to select the right next step; it does not promise that every numeric failure identifies one unique root cause in the whole system.
