Package fi.bitwards.service

Error & Reason Code Reference

This document lists every error code and reason code surfaced through the BitwardsService SDK API.

Error codes arrive via BitwardsService.NFCResourceCallback.onError(BitwardsResource, int) on resource callback interfaces and via BitwardsService.ResultCallback.onError(int) on general operations. Error codes may also be received as a BitwardsException: some SDK methods throw BitwardsException rather than delivering errors through a callback, and BitwardsException.getErrorCode() returns the same ERROR_* integer constants documented here.

Reason codes arrive exclusively via BitwardsService.NFCResourceCallback.onAccessDenied(BitwardsResource, int). They are returned by the physical reader (lock/reader firmware) and translated into the constants listed here. Reason code integers start at 256 (0x100).

Codes are grouped by logical function, not by numeric value. Numeric values are shown in the Value column.

Search by Method / Callback

Type a method or callback name to list all error codes it can emit.

Search by method name: login, logout, refresh, synchronize, changePassword, updateBitwardsUser, isAuthenticationTokenValid, deleteUserAccount, setNFCResourceCallback, discoverAndAccessResource, accessResource, maintainResource, scanAndAccessResource, registerBackgroundScanCallback, stopBackgroundScan, unregisterBackgroundScanCallback, startBluetoothProximityAccess  —  or by callback / source: NFCResourceCallback, BLEResourceCallback, BackgroundScanCallback, ResultCallback, onError, onAccessDenied, BitwardsException, getErrorCode, onFailure

Contents

Commonality key: Very Common frequently encountered in normal use Common seen in typical usage scenarios Uncommon specific scenarios / edge cases Rare narrow edge cases Dev error usually a programming mistake Deprecated
Emission sources

Each code in the tables below is tagged with the letter(s) of the callback or throw mechanism that delivers it.

A
NFC Resource Callback — BitwardsService.NFCResourceCallback.onError(BitwardsResource, int)
Errors on NFC access attempts
B
BLE Resource Callback — BitwardsService.BLEResourceCallback.onError(BitwardsResource, int)
Errors on BLE access attempts
C
Background Scan — BitwardsService.BackgroundScanCallback.onError(int)
Background proximity scan errors
D
Result Callback — BitwardsService.ResultCallback.onError(int)
Login, logout, sync, profile, reservation & location ops
E
Thrown Exception — BitwardsException.getErrorCode()
Synchronous pre-flight validation before async work starts
F
Access Denied — BitwardsService.NFCResourceCallback.onAccessDenied(BitwardsResource, int)
Reader-reported rejection (reason codes, both BLE and NFC)
G
Feature Callback — BitwardsInstallationTask.OnFailureCallback.onFailure(BitwardsInstallationTask, int) / BitwardsResourceUpdateTask.OnFailureCallback.onFailure(BitwardsResourceUpdateTask, int)
Reader installation and firmware/config update operations

1. BLE / NFC Hardware Error Codes

These codes are produced at the BLE/NFC transport layer, below the service-business-logic level. They come from the Android Bluetooth stack, the GATT layer, or from connection management. Value range: negative integers (−1 to −255).

Bluetooth & BLE scan errors

Error Code Value Commonality Description Via
ERROR_BLUETOOTH_NO_PERMISSION −1 Common The application does not hold the necessary Bluetooth runtime permissions. On Android 12+ this means BLUETOOTH_SCAN or BLUETOOTH_CONNECT have not been granted by the user at runtime. On earlier Android versions the legacy ACCESS_FINE_LOCATION permission covers BLE scanning. Without these permissions any attempt to start a scan or GATT connection will immediately fail with this code. BC
ERROR_BLUETOOTH_NOT_ENABLED −2 Very Common Bluetooth is switched off on the device at the time of the operation. Any scan or connection attempt will fail immediately. The user must enable Bluetooth in system settings (or the app can prompt them to do so via BluetoothAdapter.ACTION_REQUEST_ENABLE) before retrying. BC
ERROR_BLE_SCAN_FAILED −3 Common The BLE scan itself failed to start. Android imposes a limit of 5 scan start requests per 30-second window per app. Exceeding this quota causes Android to return SCAN_FAILED_APPLICATION_REGISTRATION_FAILED or similar error codes. Other causes include Bluetooth being turned off between the permission check and the actual scan start, or an internal BLE stack failure. BC
ERROR_GATT_ERROR −5 Very Common A Bluetooth GATT error occurred during the connection or data exchange phase. GATT errors (Android code 133 being the most notorious) are endemic to the Android BLE stack and can result from timing issues, device-side disconnects, radio interference, or Android's internal BLE stack instability. The javadoc explicitly notes that the operation should be retried. The service itself has internal retry logic for GATT errors. B
ERROR_DEVICE_CONNECTION_ACTIVE −6 Uncommon A GATT connection to a Bluetooth device is already open and active. The service prevents opening a second concurrent GATT connection to the same physical device to avoid Android BLE stack conflicts. This error surfaces if code tries to initiate a second access attempt while the first connection is still alive. B
ERROR_BLE_SCAN_ALREADY_ACTIVE −7 Uncommon A BLE scan is already running when a second scan start is requested. The service enforces a single scan at a time. This error ensures the existing scan is not silently abandoned by the new request. BC
ERROR_BLE_NOT_RESOURCE −8 Uncommon The Bluetooth device that was connected to is not a Bitwards resource. During scan or direct connection, the service validates the device's service UUIDs and advertisement data. If they don't match the Bitwards profile, this error is returned rather than attempting to use the device as a resource. B
ERROR_BLUETOOTH_WAS_DISABLED −10 Uncommon Bluetooth was turned off by the user (or the OS) while an operation was already in progress. This is different from ERROR_BLUETOOTH_NOT_ENABLED which detects Bluetooth being off before the operation starts. This code catches the mid-operation disablement scenario, for instance when the user swipes down to toggle Bluetooth off while a door-open attempt is underway. BC
ERROR_BAD_MAC_ADDRESS −11 Rare The Bluetooth MAC address associated with the resource is invalid or malformed. Resources are identified in the database with a MAC address that is used to target the GATT connection. If this address is corrupted, missing, or in a format the Android BLE API does not accept, the connection attempt cannot even be started. B
ERROR_GATT_READ_FAILURE −15 Uncommon A GATT characteristic read operation returned a failure result. This occurs during the data exchange phase after a connection is established, when the service tries to read a characteristic value from the reader. The javadoc explicitly states this should be treated identically to ERROR_BAD_RESOURCE. B
ERROR_FAILED_TO_SEND_LONG_RAPDU −16 Rare The Android device's BLE stack is unable to send a long RAPDU (Response Application Protocol Data Unit) message to the resource. This is a device-specific issue caused by bugs or limitations in certain Android devices' BLE implementations where segmented BLE writes fail. The javadoc notes this "typically means that the App cannot access the resource in this device", meaning the problem is with the phone, not the reader, and a different Android device would likely succeed. B

Range & connection errors

Error Code Value Commonality Description Via
ERROR_RESOURCE_OUT_OF_RANGE −12 Very Common The resource (reader) moved out of BLE range during the operation. BLE range in typical indoor environments is 5–15 metres but varies significantly based on obstructions, phone antenna quality, and reader placement. A user who was initially close enough to start a connection may walk away or be blocked before the access sequence completes. B
ERROR_RESOURCE_DISCONNECTED −13 Common The resource disconnected unexpectedly while a GATT connection was active. Unlike out-of-range, this is an explicit disconnection (GATT disconnect event) rather than a signal loss. Causes include reader firmware-initiated disconnect after a timeout, reader power cycle, or an Android BLE stack decision to drop the connection. B
ERROR_RESOURCE_TIMEOUT −14 Common The connection attempt to the resource timed out. This happens when a GATT connection is initiated but no successful connection is established within the allowed time window. Causes include the resource being out of range at connection-initiation time, the resource being busy serving another connection, or slow advertisement interval on the resource side. B

Resource & NFC errors

Error Code Value Commonality Description Via
ERROR_BAD_RESOURCE −4 Uncommon The resource (reader hardware) is malfunctioning. This is the general catch-all for reader-side faults: the device connected successfully via GATT but subsequent communication indicated the reader is in a bad state, returning unexpected data or error responses. Hardware faults, reader firmware crashes, or low battery causing partial failure can produce this error. AB
ERROR_NFC_NO_PERMISSION −9 Rare The application does not have the NFC permission at the transport layer. NFC permission (android.permission.NFC) is a normal (not dangerous) permission and is typically granted automatically at install time if declared in the manifest. This error appearing at runtime would indicate the permission is missing from the manifest or a custom ROM is enforcing it differently. A
ERROR_RESOURCE_UNKNOWN_ERROR −255 Rare An unexpected, unclassified error occurred at the BLE/NFC transport layer. This is the catch-all for error conditions that do not match any of the specific negative error codes. It may indicate an undocumented Android BLE API error, a firmware edge case, or a code path that was not fully mapped to a specific error code. AB

2. Service Error Codes — Authentication & Session

Errors produced during login, logout, OAuth token lifecycle, and session management. Value range: positive integers.

Error Code Value Commonality Description Via
ERROR_UNKNOWN 1 Rare An unknown or otherwise unclassified error occurred within the service. This is the generic catch-all at the service level — if an exception or error condition does not map to a more specific code, this value is returned. It indicates that an unexpected state was reached and the service could not determine a more precise cause. ABDE
ERROR_NO_INTERNET 2 Common The device does not have an active internet connection at the time of a network-dependent operation (login, resource list fetch, credential refresh, etc.). The service checks for connectivity before attempting network calls and returns this code immediately rather than waiting for a request timeout. Offline BLE/NFC access using already-downloaded credentials is still possible when this error applies. D
ERROR_NOT_LOGGED_IN 4 Common The operation requires an authenticated session but the user is not currently logged in. The BitwardsService instance is not connected to the Bitwards backend. This appears on the first launch before login, after a logout, or if the stored session was invalidated. Most SDK operations that require server communication will return this if called without a valid session. DE
ERROR_ALREADY_LOGGED_IN 5 Dev error A login attempt was made when a user session is already active. The service enforces a single active session; a second login call is rejected with this code. The caller must log out the existing user before logging in a new one. E
ERROR_LOGIN_FAILED 6 Common The login attempt failed for a general reason not covered by the more specific login error codes. Causes include wrong credentials, an OAuth authorization server rejecting the request, network issues that are not a clean connectivity failure, or server-side validation errors. This is the baseline login failure code and may appear when neither a server error (17) nor a "user does not exist" (58) condition is detected. D
ERROR_LOGOUT_FAILED 7 Uncommon The logout request to the Bitwards backend failed, for example due to a network error or server-side problem when trying to invalidate the session token. Note that even if the server-side logout fails, the local session state may still be cleared; the exact behaviour depends on the implementation. DE
ERROR_LOGIN_FAILED_DUE_TO_SERVER_ERROR 17 Uncommon Login failed because the Bitwards backend returned a 5xx-class server error or an otherwise internal error response. This distinguishes a backend outage scenario from a credential error. The user's credentials may be correct; the problem is on the server side. Retrying after a delay is appropriate. D
ERROR_LOGIN_FAILED_BECAUSE_USER_DOES_NOT_EXISTS 58 Uncommon Login failed because the server returned a response indicating the user account does not exist. This can happen if the user is trying to log in with an email address that was never registered, or if the account was deleted from the backend. D
ERROR_AUTH_TOKEN_EXPIRED 29 Common The OAuth2 authentication token used to communicate with the server has expired. The service periodically refreshes tokens, but if the refresh itself fails (network down, refresh token expired, server rejects refresh), subsequent API calls will fail with this code. The user needs to log in again to obtain a new valid token pair. D
ERROR_RELOGIN_REQUIRED 62 Common The OAuth2 token refresh failed because the user must re-authenticate — the refresh token has expired or been revoked. This is issued as a logout reason rather than a direct error from a user-initiated action. The service detects that the refresh token can no longer be used to silently renew the access token and forces the user to log in again with their credentials. D
ERROR_USER_LOGGED_OUT 63 Common A logout reason code indicating the end user explicitly initiated logout. This is used in logout reason reporting to distinguish a voluntary logout from a forced logout due to token expiry or server rejection. It allows the app to differentiate user-initiated flow ("logged out successfully") from system-initiated flow ("session expired"). D

3. Service Error Codes — User Profile

Errors from user account management operations.

Error Code Value Commonality Description Via
ERROR_CHANGE_PASSWORD_FAILED 8 Uncommon The password change request for the currently logged-in user failed. This can be caused by incorrect current password, server-side validation failure (e.g., new password does not meet policy requirements), network errors, or server errors during the update operation. D
ERROR_GET_USER_PROFILE_FAILED 9 Uncommon Fetching the user profile data from the Bitwards backend failed. The request may have failed due to a network error, an expired session, or a server-side error. User profile data includes display name, email, and settings. D
ERROR_CHANGE_USER_PROFILE_FAILED 10 Uncommon Updating the user profile (e.g., changing display name or other editable profile fields) failed. The update request to the backend did not complete successfully. Causes mirror those of ERROR_GET_USER_PROFILE_FAILED. D
ERROR_ACCOUNT_DELETION_FAILED 61 Rare The account deletion request failed. Attempting to permanently delete a Bitwards user account via the SDK's account-deletion API returned an error. This may occur due to network failure, server-side errors, or because the account has dependencies (e.g., active resources) that prevent deletion. D

4. Service Error Codes — Initialization & Connection

Errors related to the SDK lifecycle: initialization, connection to the backend, and resource list retrieval.

Error Code Value Commonality Description Via
ERROR_INITIALIZATION_FAILED 12 Uncommon Initialization of the BitwardsService instance failed. Initialization sets up the local database, loads persisted credentials, and prepares BLE/NFC subsystems. Failure may result from an invalid license key, database corruption, or a critical subsystem being unavailable. E
ERROR_NOT_INITIALIZED 13 Dev error An SDK method was called before BitwardsService was initialized. The service is a singleton that must be initialized exactly once before use. Calling any operation on an uninitialized instance returns this code immediately without performing any work. E
ERROR_ALREADY_INITIALIZED 14 Dev error The BitwardsService instance is already initialized and a second initialization was attempted. Because the service is a singleton, repeated initialization calls are rejected. The application must ensure initialization is performed only once per app process lifecycle. E
ERROR_NOT_CONNECTED 15 Common The BitwardsService instance is initialized but not connected to the Bitwards backend. This state occurs after initialization but before a successful login/connect, or after a connection was lost and not yet re-established. Operations that require a live server connection will fail with this code. DE
ERROR_GET_RESOURCE_LIST_FAILED 11 Uncommon Fetching the list of Bitwards resources (access points) available to the logged-in user from the server failed. This is a network-dependent operation performed after login and periodically refreshed. Failure may be due to network errors, session expiry, or server-side issues. D
ERROR_REFRESH_FAILED 48 Common Refreshing the connection to the backend server failed. The service periodically re-syncs credentials, resource lists, and access tokens. If this sync fails — for instance due to temporary network loss or server downtime — this error is returned. A successful refresh would have updated locally cached data and renewed tokens. D
ERROR_RESOURCE_NULL 28 Dev error A BitwardsResource object passed to an SDK method was null. Resource-related operations require a valid, non-null resource reference. This error is a null-guard that surfaces immediately to the caller rather than causing a NullPointerException. ABE

5. Service Error Codes — Permissions

Errors from missing Android runtime permissions, checked at the service layer before attempting any BLE or NFC operation.

Error Code Value Commonality Description Via
ERROR_NO_LOCATION_PERMISSION 19 Common The application does not have the ACCESS_FINE_LOCATION permission. On Android 6–11, this is required for BLE scanning because Bluetooth scans can be used to infer location. The user must grant this permission at runtime. On Android 12+ BLE scanning no longer requires location permission (it requires BLUETOOTH_SCAN instead, see code 59), so this error is primarily seen on older OS versions. BCE
ERROR_NO_NFC_PERMISSION 20 Rare The application does not have the android.permission.NFC permission. This is a normal (install-time) permission that is automatically granted when declared in the manifest. In practice this should never occur in a correctly built app; it would only appear if the manifest declaration is missing or a custom Android ROM enforces it as a runtime permission. AE
ERROR_NO_READ_DEVICE_STATE_PERMISSION 21 Rare The application does not have the READ_PHONE_STATE or device state permission. This permission may be needed on certain Android versions or device configurations for specific SDK subsystems to query device state. In the current SDK usage, it is checked in some code paths and failing the check causes this error. E
ERROR_NO_BLUETOOTH_SCAN_PERMISSION 59 Common The application does not have the BLUETOOTH_SCAN permission, which was introduced in Android 12 (API 31) to allow BLE scanning without requiring location permission. This is a runtime permission that must be explicitly requested and granted by the user. Any BLE scan attempt will fail with this code on Android 12+ if the permission has not been granted. BCE
ERROR_NO_BLUETOOTH_CONNECT_PERMISSION 60 Common The application does not have the BLUETOOTH_CONNECT permission, introduced in Android 12 (API 31). This permission is required to establish GATT connections to Bluetooth devices. Without it, even if a scan succeeds, the actual connection phase will be blocked by the OS. It must be requested and granted at runtime. BCE

6. Service Error Codes — Bluetooth / BLE / Location Services

Errors at the service layer related to Bluetooth availability, scan state, and Android location service requirements.

Error Code Value Commonality Description Via
ERROR_BLUETOOTH_NOT_AVAILABLE 22 Rare The Android device does not support Bluetooth at all. The SDK checks for BluetoothAdapter availability and if the device has no Bluetooth hardware, this error is returned. In practice virtually all modern Android devices have Bluetooth, so this is essentially only seen on some emulators or unusual embedded devices. BE
ERROR_BLE_ALREADY_ACTIVE 16 Uncommon A Bluetooth operation (scan or connection) is already active at the service level when a new one is requested. The service enforces serialization of BLE operations to avoid conflicts in the Android BLE stack. The caller must wait for the current operation to complete or be cancelled before starting a new one. BE
ERROR_BLE_SCAN_NOT_ACTIVE 24 Dev error An attempt was made to stop a BLE scan but no scan is currently active. This can happen if the caller calls a stop-scan method without having successfully started a scan, or after the scan has already stopped due to an error or completion. The service validates that a scan is running before processing a stop request. E
ERROR_NFC_NOT_AVAILABLE 23 Uncommon The Android device does not have NFC hardware. While most mid-range and high-end Android devices have NFC, it is still absent on some budget devices and most tablets. Any attempt to use NFC-based resources on such a device will fail with this code. AE
ERROR_LOCATION_SERVICE_DISABLED 50 Common The Android device's Location service (GPS / network location) is completely disabled in device settings. On Android 6–11, BLE scanning requires not just the ACCESS_FINE_LOCATION permission but also that the Location service itself is enabled at the OS level. If the user has turned off Location in the quick-settings panel or system settings, BLE scans will fail even if the permission is granted. BC
ERROR_UNKNOWN_BACKGROUND_SCAN_MODE 30 Dev error An unknown or invalid background scan mode constant was passed to a background scan configuration method. The service supports a specific set of background scan modes (e.g., RESOURCE_SCAN_MODE_KNOWN, proximity-based modes). Passing an integer that does not correspond to a defined mode results in this error rather than silent undefined behaviour. CE
ERROR_BACKGROUND_SCAN_STOPPED 56 Common The background scan was intentionally stopped rather than failing due to an error. This code is delivered via BackgroundScanCallback.onError() to signal that the scan has ended cleanly as a result of a stop request. It is informational rather than a true error; the caller should update UI or internal state to reflect that background scanning is no longer active. C
ERROR_SECURE_DEVICE_LOCK_NOT_ENABLED 25 Deprecated Previously required that the Android device had a secure lock screen (PIN, pattern, fingerprint) enabled as a condition for using the SDK. This requirement was removed from the SDK, and this error code is now deprecated and is no longer returned in normal operation. Deprecated. Kept for ABI compatibility only. Do not test for this code in new integrations.

7. Service Error Codes — Operational

General-purpose service-layer errors that appear across multiple SDK operations.

Error Code Value Commonality Description Via
ERROR_CALLBACK_NULL 18 Dev error A null callback was passed to an SDK method that requires a non-null callback to deliver results. Since the SDK is callback-based, passing a null callback would prevent results from ever being delivered. The service validates callbacks at the point of entry and immediately returns this error rather than storing a null and crashing later. E
ERROR_ANOTHER_OPERATION_ONGOING 26 Uncommon A new operation was requested while another operation of the same type is already in progress. The service serializes certain operations (such as access attempts to the same resource, or certain server operations) to prevent concurrent state corruption. The new operation is rejected until the existing one completes. ABE
ERROR_TIMEOUT 27 Common A service-level operation exceeded its allowed time limit. This is the service-layer timeout, distinct from the BLE-layer ERROR_RESOURCE_TIMEOUT (−14). It may be returned for server communication timeouts (when the backend does not respond within the configured window) or for other timed operations managed at the service level. ABD
ERROR_ACCESS_FORBIDDEN 57 Uncommon The server returned HTTP 403 Forbidden in response to a service request. The logged-in user does not have permission to access the requested backend service or resource endpoint. This differs from access denied at the reader level (which comes as a reason code): this is an API-level authorization failure, meaning the user's account does not have the right to call the specific server endpoint. D

8. Reason Codes — Token & Credential Validation

These reason codes are returned via BitwardsService.NFCResourceCallback.onAccessDenied(BitwardsResource, int). They originate in the physical reader's firmware: the app presents a cryptographic access token over BLE/NFC, and the reader evaluates it, returning one of these status codes if the token is rejected. Reader-reported reason codes start at base 256 (0x100).

Reason Code Value Commonality Description Via
REASON_NO_VALID_TOKEN 516 Very Common The application does not possess a valid access token for this resource. This occurs when the user has not been granted access rights to this specific resource in the Bitwards backend, or when the locally cached token has been deleted or has expired and a new one has not yet been downloaded. The reader is not even consulted in this case — the rejection happens application-side before any BLE/NFC communication. F
REASON_BAD_DATA 257 Rare The reader rejected the token because the data it received was malformed or corrupted. This means the BLE/NFC communication delivered data to the reader, but the reader's firmware determined the received bytes do not constitute a valid token structure. Causes include data corruption in transit, a bug in token serialization, or a partial transmission. F
REASON_WRONG_SIGNATURE 258 Rare The reader verified the token's cryptographic signature and found it invalid. The token's signature does not match what the reader's stored key would produce for the given data. This could indicate a token generated with the wrong key, a tampered token, or a key mismatch between the app and the reader (e.g., after a reader re-key or provisioning issue). F
REASON_WRONG_DELEGATION 259 Uncommon The delegation chain embedded in the token is invalid. Bitwards tokens can include a delegation hierarchy where access rights are delegated from an owner to a user. If the delegation structure is malformed, references a wrong parent token, or was created by an entity not authorized to delegate, the reader rejects it with this code. F
REASON_DELEGATION_USED 260 Uncommon The presented delegation token has already been used. Certain delegation tokens are single-use to prevent replay attacks. Once the reader records a delegation as used in its cache, any subsequent presentation of the same token is rejected with this code. The user needs a fresh token from the server. F
REASON_DELEGATION_CACHE_OVERRUN 261 Rare The reader's internal cache for tracking used delegations has run out of space. Readers store a bounded set of recently-used delegation token IDs to detect replays. If this cache fills up (due to very high access volume or a small cache size), new delegations cannot be tracked and will be rejected with this code until the cache is cleared (typically by a reader restart or firmware operation). F
REASON_TOKEN_BLACKLISTED 262 Uncommon The presented access token has been explicitly blacklisted on the reader. Readers can store a blacklist of revoked token identifiers. If an administrator revokes a specific token (e.g., due to credential compromise or key replacement) and the revocation is pushed to the reader's blacklist, subsequent presentations of that token will be denied with this code. F
REASON_WRONG_TIME_WINDOW 263 Common The token's time window does not include the current moment. Bitwards tokens embed a validity time window (start time and end time). If the reader's clock shows that the current time falls outside this window (too early or too late), the token is rejected. This is a core mechanism for time-limited access control — users with schedules can only access during their allowed hours. F
REASON_CREATIONTIME_IN_FUTURE 264 Uncommon The token's creation timestamp is set to a time in the future relative to the reader's current time. This can happen due to clock skew between the Bitwards server (which creates tokens) and the reader's internal clock. If the server clock is significantly ahead of the reader, freshly issued tokens appear to be "from the future" and are rejected as potentially invalid. F

9. Reason Codes — Schedule-Based Denial

Reason codes returned when the reader denies access because the attempted access time falls outside a configured access schedule.

Reason Code Value Commonality Description Via
REASON_OPERATION_DENIED_BY_REGULAR_SCHEDULE 271 Very Common Access was denied because the current day and time fall outside the resource's regular (recurring weekly) access schedule. Bitwards resources can be configured with weekly schedules — for example, "allowed Monday–Friday, 08:00–18:00." An access attempt outside this window is denied at the reader level with this reason code, regardless of whether the user holds a valid token. The schedule is stored on the reader itself. F
REASON_OPERATION_DENIED_BY_EXCEPTION_SCHEDULE 272 Common Access was denied due to an exception schedule entry. Exception schedules override the regular schedule for specific dates (e.g., public holidays, special events, building closures). When an exception schedule entry is active for the current date, it takes precedence over the regular schedule. If the exception marks the day as closed/restricted, access is denied with this code. F

10. Reason Codes — Hardware & Resource State

Reason codes related to the physical state of the reader or its peripheral components (door actuator, lock motor, battery, etc.).

Reason Code Value Commonality Description Via
REASON_HANDLE_IN_WRONG_POSITION 274 Common The door handle or actuator is in the wrong physical position for the requested operation. For example, on doors with lever handles, the handle may need to be in a neutral (up) position before the lock can engage or disengage. If the user presents their credential while the handle is depressed, tilted, or in a mechanical state that prevents the lock from operating, the reader firmware returns this code. The user must release the handle, wait, and retry. F
REASON_PERIPHERAL_FAILURE 268 Uncommon A peripheral component connected to the reader (e.g., an external electric strike, motor, or relay) experienced a failure. The reader itself processed the token successfully, but when attempting to actuate the lock mechanism, the peripheral device reported an error. This could be a wiring issue, a failed actuator, or an external power supply problem. F
REASON_PERIPHERAL_COMMUNICATION_FAILURE 269 Uncommon Communication between the reader and its peripheral component failed. Unlike REASON_PERIPHERAL_FAILURE where the peripheral itself is faulty, this code indicates a communication link failure — the reader could not successfully exchange signals with the connected peripheral (e.g., a Wiegand or RS485 interface issue, broken cable, or misconfiguration). F
REASON_OPERATION_FAILED_BATTERY_CRITICAL 270 Uncommon The operation failed because the reader's battery level is critically low. Battery-powered readers (e.g., standalone wireless locks) may refuse to operate the lock mechanism when battery is near-depleted to prevent getting stuck in an open or closed state. The reader firmware proactively rejects access attempts when it detects critically low battery to prompt maintenance before complete failure. F

11. Reason Codes — Access Policy

Reason codes related to role-based, reservation, and protocol compatibility access policy enforcement.

Reason Code Value Commonality Description Via
REASON_RESOURCE_ALREADY_RESERVED 266 Uncommon The resource is currently reserved by another user and therefore cannot be accessed. This reason code is relevant in deployments that use the reservation system (booking meeting rooms, shared vehicles, etc.). If a user attempts to access a resource that has an active reservation belonging to someone else, the reader or the application-level logic returns this code. F
REASON_ILLEGAL_USER_ROLE 267 Uncommon The token owner's user role is not permitted to perform the requested operation on this resource. Bitwards supports role-based access control where different user roles (e.g., "user", "admin", "installer") have different permission levels. If a user with an insufficient role presents a token for an operation that requires a higher role, the reader rejects it with this code. F
ERROR_RESOURCE_REQUIRES_APP_UPDATE 273 Uncommon The resource is using a BLE/NFC protocol version that the current application does not support. This happens when reader firmware has been updated to use a newer version of the Bitwards access protocol but the mobile app has not yet been updated to understand it. The reader rejects the communication because the app is speaking an outdated protocol dialect. F

12. Service Error Codes — Resource Installation

These error codes are only applicable if the application intends to support resource installation functionality. Applications that do not perform reader provisioning will never encounter these codes.

Errors produced during the installation (provisioning) of a new Bitwards resource (physical reader). Installation involves BLE communication with the reader and registration with the backend.

Error Code Value Commonality Description Via
ERROR_INSTALLATION_FAILED 33 Common The installation of a Bitwards resource failed without a more specific sub-reason. This is the catch-all installation failure. BLE communication with the reader may have failed part-way through the provisioning sequence, or the backend registration failed without returning a classifiable error response. G
ERROR_RESOURCE_ALREADY_INSTALLED 34 Common Installation failed because this resource has already been installed locally in the device's database. The SDK prevents double-installation of the same physical reader to avoid duplicate database entries and conflicting state. If the user attempts to install a reader they have already installed, this error is returned. GE
ERROR_SERVER_RESPONSE_RESOURCE_ALREADY_INSTALLED 38 Common The server rejected the installation because the resource is already registered on the backend. This happens when a reader's serial number is already associated with an existing installation in the Bitwards system. The reader may have been previously installed by this user on another device, or by another user. G
ERROR_SERVER_RESPONSE_INTERNAL_ERROR 39 Uncommon The server returned an internal error response during the installation process. This is a 5xx-class server-side failure during the resource registration call. The physical reader may be in a partially provisioned state; retrying the installation after the server issue is resolved may be necessary. G
ERROR_SERVER_RESPONSE_FAILED_TO_ADD_NEW_RESOURCE_IN_SERVER 40 Uncommon The server failed to register the new resource in its database during the installation flow. This is distinct from an internal server error (39) in that the server processed the request but explicitly responded that it could not add the new resource, possibly due to a license limit, configuration issue, or data validation failure. G
ERROR_SERVER_RESPONSE_SERIAL_NUMBER_ALREADY_EXISTS 41 Uncommon The server rejected the installation because the reader's serial number is already registered in the system. This is a specific variant of the "already installed" server response, focusing on the serial number uniqueness constraint. The hardware serial number of the reader must be unique within the Bitwards system. G
ERROR_INSTALLATION_TEST_FAILED 49 Uncommon The installation completed (all installation messages were successfully delivered to the reader) but the subsequent access test failed. After installing a reader, the SDK performs a test access attempt using a test token to verify the reader is fully operational. If this test fails, the installation is reported as partially successful — the reader was provisioned but could not be verified as working. G
ERROR_INSTALLATION_NOT_ACTIVE 31 Dev error An installation operation was attempted or cancelled but no installation is currently in progress. The service enforces that certain installation management calls (e.g., cancel) are only valid when an installation task is active. This error appears if the caller attempts to cancel an installation that was never started or has already completed. GE
ERROR_INSTALLATION_ACTIVE 32 Uncommon A new installation was requested while a previous installation is still in progress. The service handles one installation at a time. Starting a second installation before the first completes is rejected with this code. GE
ERROR_INSTALLATION_TASK_NOT_PENDING 35 Dev error The installation task is not in a pending state when an operation that requires it to be pending was requested. Installation tasks have a lifecycle (pending → active → complete). Attempting to perform a state transition on a task that is not in the expected pending state yields this error. GE
ERROR_INSTALLATION_TASK_CANCELLED 37 Common The installation task was cancelled. This is returned via the installation callback to confirm that a cancellation request was processed and the installation was aborted. It is not a failure in the traditional sense but an acknowledgement that the user or application deliberately stopped the installation process. G
ERROR_WRONG_INSTALLATION_TASK_CANCELLED 36 Rare A cancellation request was received for an installation task that does not match the currently active installation. This can happen in concurrent or out-of-order scenarios where a cancel request refers to an old or non-existent task while a different installation is underway. GE

13. Service Error Codes — Reservation

These error codes are only applicable if the application plans to use the resource reservation functionality. Applications that do not support booking or time-slot reservation of resources will never encounter these codes.

Errors from the resource reservation API, used for booking/reserving time-shared resources.

Error Code Value Commonality Description Via
ERROR_SERVER_RESPONSE_RESOURCE_RESERVATION_FAILED 44 Uncommon The server returned a failure response when attempting to make a resource reservation. The reservation request reached the server but was rejected — the resource may already be booked for the requested time slot, the user may lack permission to reserve it, or a server-side validation rule prevented the booking. D
ERROR_RESOURCE_RESERVATION_SERVER_COMMUNICATION 45 Uncommon A network or communication error occurred while attempting to make a resource reservation. The request did not reach the server or a valid response was not received due to connectivity issues, timeout, or protocol error. D
ERROR_SERVER_RESPONSE_CANCEL_RESOURCE_RESERVATION_FAILED 42 Uncommon The server returned a failure when attempting to cancel an existing resource reservation. The cancellation request was received by the server but rejected — the reservation may have already expired, already been cancelled, or the user may not have permission to cancel it. D
ERROR_CANCEL_RESOURCE_RESERVATION_SERVER_COMMUNICATION 43 Uncommon A network or communication error occurred while attempting to cancel a resource reservation. The cancellation request could not be delivered to the server due to connectivity issues. D
ERROR_SERVER_RESPONSE_GET_LOCATION_LIST_FAILED 46 Uncommon The server returned an error response when the SDK requested the list of locations (physical sites/buildings). Locations are used to group resources and may be displayed in the UI or used for filtering. A server-side error in fetching this list is returned with this code. D
ERROR_GET_LOCATION_LIST_SERVER_COMMUNICATION 47 Uncommon A network or communication error occurred when fetching the location list from the server. The request could not be completed due to connectivity issues, timeout, or protocol error. D

14. Service Error Codes — Resource Update

These error codes are only applicable if the application intends to support resource update functionality. Applications that do not push firmware or configuration updates to installed readers will never encounter these codes.

Errors from the resource firmware/configuration update process, used to push updates to installed readers over BLE.

Error Code Value Commonality Description Via
ERROR_RESOURCE_UPDATE_FAILED 51 Uncommon The resource update process failed. Updating a resource involves BLE communication to deliver new firmware or configuration data to the physical reader. Failure may occur due to BLE errors during data transfer, the reader rejecting the update, or a server communication failure when fetching the update payload. G
ERROR_RESOURCE_UPDATE_ACTIVE 52 Dev error A new resource update was requested while a previous update is already in progress. Only one resource update can be active at a time. The new request is rejected until the current update completes or is cancelled. GE
ERROR_RESOURCE_UPDATE_TASK_CANCELLED 53 Uncommon The resource update task was cancelled. This confirms that a cancellation request was processed and the update was aborted. Returned via the update callback to signal deliberate user or application cancellation rather than an error. G
ERROR_RESOURCE_UPDATE_NOT_ACTIVE 54 Dev error An update management operation (e.g., cancel) was called but no update is currently active. Mirrors ERROR_INSTALLATION_NOT_ACTIVE in pattern: the service enforces that certain operations are only valid in the context of an active update. GE
ERROR_WRONG_RESOURCE_UPDATE_TASK_CANCELLED 55 Rare A cancellation request targeted an update task that does not match the currently active update. Mirrors ERROR_WRONG_INSTALLATION_TASK_CANCELLED (36) in pattern. Can occur in race conditions where task identities become mismatched. GE

Generated from BitwardsService.java · BitwardsException.java · Bitwards SDK 3.6.11