> For the complete documentation index, see [llms.txt](https://docs.bituo-technik.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bituo-technik.com/device-api/spm-sdm-open-wi-fi-api-overview/error-code-reference.md).

# Error Code Reference

{% hint style="info" %}
**Status:** Active | **Applies to:** all branches, all channels | Based on the device error-code table and the configuration subcodes | **Updated:** 2026-10-16&#x20;
{% endhint %}

### 1. How to read `code`

When a JSON response on any channel **fails**, an integer `code` is added next to `msg` and `event`. A **successful response has no `code`**, so check `ok` (or `result` in the legacy format) first to decide success.

<table><thead><tr><th width="212.3333740234375">code</th><th>Meaning</th></tr></thead><tbody><tr><td>absent</td><td>Success</td></tr><tr><td><code>-1</code></td><td>The firmware gave this failure no specific number; judge from <code>ok</code> and <code>msg</code></td></tr><tr><td>1000 to 1999</td><td>BLE channel</td></tr><tr><td>2000 to 2999</td><td>HTTP / HTTPS channel</td></tr><tr><td>3000 to 3999</td><td>MQTT channel</td></tr><tr><td>4000 to 4999</td><td>WebSocket channel</td></tr></tbody></table>

Failures without any `code` exist too: for example an MQTT command above 1024 bytes or with a JSON parse error is simply dropped and nothing is sent back.

**Always read `msg` and `event` together with `code`.** Configuration errors are "channel base + subcode", and fixed codes live in the same ranges, so numbers collide (see Section 6). `msg` is the English original from the device, and matching on it is the most reliable.

### 2. Configuration subcodes

When a business command (`wifi`, `mqtt`, `udp`, ...) fails, its English `msg` maps to a subcode `s`, and `code = channel base + s`: BLE `1000 + s`, HTTP `2000 + s`, MQTT `3000 + s`, WebSocket `4000 + s`.

<table><thead><tr><th width="110.888916015625">s</th><th>msg</th><th>Description</th></tr></thead><tbody><tr><td>1</td><td>(empty <code>msg</code>)</td><td>Unclassified failure</td></tr><tr><td>2</td><td><code>Error password length!</code></td><td>New password too long</td></tr><tr><td>3</td><td><code>auth error</code></td><td>Auth string wrong or wrong length</td></tr><tr><td>4</td><td><code>bad value</code></td><td>Invalid numeric parameter (for example report interval)</td></tr><tr><td>5</td><td><code>unsupported</code></td><td>Command not supported by this model or branch</td></tr><tr><td>6</td><td><code>null</code></td><td>No data for this model (for example no schedule)</td></tr><tr><td>7</td><td><code>lorawan unsupported</code></td><td>This model has no LoRaWAN</td></tr><tr><td>8</td><td><code>lorawan rejoin failed</code></td><td>LoRaWAN rejoin failed</td></tr><tr><td>9</td><td><code>lorawan upload failed</code></td><td>LoRaWAN upload queue failed</td></tr><tr><td>10</td><td><code>lorawan region password failed</code></td><td>Region change password wrong</td></tr><tr><td>11</td><td><code>lorawan region failed</code></td><td>Region update failed</td></tr><tr><td>12</td><td><code>lorawan config disabled</code></td><td>LoRaWAN configuration disabled</td></tr><tr><td>13</td><td><code>lorawan config save failed</code></td><td>LoRaWAN configuration save failed</td></tr><tr><td>14</td><td><code>functionMap error</code></td><td>Channel combination invalid or over the limit</td></tr><tr><td>15</td><td><code>unknow cmd</code></td><td>Unknown command (spelled like this in the firmware)</td></tr><tr><td>16</td><td><code>Timer not found</code></td><td>Timer does not exist</td></tr><tr><td>17</td><td><code>Invalid timer</code></td><td>Invalid timer parameters</td></tr><tr><td>18</td><td><code>Error wifi ssid/pass required!</code></td><td>SSID or password missing</td></tr><tr><td>19</td><td><code>Error wifi length!</code></td><td>Wi-Fi parameter length invalid</td></tr><tr><td>20</td><td><code>Error wifi reset in progress</code></td><td>Wi-Fi is reconnecting; try again later</td></tr><tr><td>21</td><td><code>Error mqtt data empty!</code></td><td>A required MQTT field is empty</td></tr><tr><td>22</td><td><code>Error length!</code></td><td>MQTT or other field length error</td></tr><tr><td>23</td><td><code>cafile error</code></td><td>Root certificate write flow error</td></tr><tr><td>24</td><td><code>UDP full</code></td><td>UDP target list full (5), or IP / port invalid</td></tr><tr><td>25</td><td><code>UDP not found</code></td><td>The UDP target to delete does not exist</td></tr><tr><td>26</td><td><code>Old Password Error</code></td><td>Old password wrong</td></tr><tr><td>27</td><td><code>Error name length!</code></td><td>Name too long</td></tr><tr><td>28</td><td><code>mda format error</code></td><td>Register extension data format error</td></tr><tr><td>29</td><td><code>mda failed</code></td><td>Register extension processing failed</td></tr><tr><td>30</td><td><code>minvert data format error</code></td><td>Inversion configuration format error</td></tr><tr><td>31</td><td><code>minvert save failed</code></td><td>Inversion configuration save failed</td></tr><tr><td>32</td><td><code>minvert data length error</code></td><td>Inversion configuration length error</td></tr><tr><td>33</td><td><code>minvert data error</code></td><td>Inversion configuration data error</td></tr><tr><td>34</td><td><code>minvert missing data</code></td><td>Inversion configuration data missing</td></tr><tr><td>35</td><td><code>bleota no data</code></td><td>BLE OTA received no data</td></tr><tr><td>36</td><td><code>bleota err param</code></td><td>BLE OTA invalid parameters</td></tr><tr><td>37</td><td><code>bleota err state</code></td><td>BLE OTA state error (not started or already done)</td></tr><tr><td>38</td><td><code>bleota err seq</code></td><td>BLE OTA packet sequence broken; transfer aborted</td></tr><tr><td>39</td><td><code>bleota err crc</code></td><td>BLE OTA CRC check failed</td></tr><tr><td>40</td><td><code>bleota err write</code></td><td>BLE OTA partition write failed</td></tr><tr><td>41</td><td><code>bleota err size</code></td><td>BLE OTA firmware size over the limit</td></tr><tr><td>42</td><td><code>bleota err unknown</code></td><td>BLE OTA unknown error</td></tr><tr><td>43</td><td><code>scan busy</code></td><td>Wi-Fi scan in progress; cannot trigger again</td></tr><tr><td>44</td><td><code>scan not ready</code></td><td>Wi-Fi scan result not ready</td></tr><tr><td>45</td><td><code>ota mem insufficient</code></td><td>Not enough memory to upgrade</td></tr><tr><td>46</td><td><code>Error enablehttps!</code></td><td>Invalid <code>enablehttps</code> parameter (Pro only)</td></tr></tbody></table>

An English `msg` not in this table that is not an error text usually means success or a neutral hint and has no `code`.

SRS relay products also have switch-extension subcodes 51 (`illegal cmd`), 52 (`Error name!`), 53 (`Error name length!`) with the same formula. SRS products are not covered by this repository.

### 3. BLE fixed error codes (1000s)

<table><thead><tr><th width="104.22216796875">code</th><th width="326">msg</th><th>Description</th></tr></thead><tbody><tr><td>1000</td><td><code>auth error</code></td><td>Phone auth string does not match the device</td></tr><tr><td>1001</td><td><code>not authenticated</code></td><td>Authentication not completed</td></tr><tr><td>1002</td><td><code>Please unlock</code></td><td>Unlock first; <code>event</code> is <code>pas</code> on the write characteristic notification and <code>read</code> on the read characteristic</td></tr><tr><td>1003</td><td><code>Password Error</code></td><td>BLE password wrong</td></tr><tr><td>1004</td><td><code>No cmd</code></td><td><code>cmd</code> missing</td></tr><tr><td>1005</td><td><code>No data received</code></td><td>Switch-extension configuration missing parameters</td></tr><tr><td>1010</td><td><code>secure channel required</code></td><td>Establish the secured channel first</td></tr><tr><td>1011</td><td><code>cipher envelope required</code></td><td>A ciphertext envelope is required</td></tr><tr><td>1012</td><td><code>decrypt failed</code></td><td>Decryption failed</td></tr><tr><td>1013</td><td><code>payload too large</code></td><td>Decrypted or secured payload too long</td></tr><tr><td>1014</td><td><code>plain json invalid</code></td><td>JSON invalid after decryption</td></tr><tr><td>1015</td><td><code>missing cmd</code> / <code>cipher envelope required</code></td><td>Command missing, or envelope incomplete</td></tr><tr><td>1020</td><td><code>version failed</code></td><td>Secured protocol version negotiation failed</td></tr><tr><td>1021</td><td><code>invalid step</code></td><td>Reset flow step mismatch</td></tr><tr><td>1022</td><td>—</td><td>J-PAKE not active when resetting the session</td></tr><tr><td>1030</td><td><code>no pending round1 response</code></td><td>No pending Round1 response to fetch</td></tr><tr><td>1031</td><td><code>client nonce mismatch</code></td><td>Client nonce mismatch</td></tr><tr><td>1032</td><td><code>round1 response unavailable</code></td><td>Round1 response unavailable</td></tr><tr><td>1033</td><td><code>invalid step</code></td><td>J-PAKE Round1 step error</td></tr><tr><td>1034</td><td><code>invalid round1 chunk</code></td><td>Invalid chunk parameters</td></tr><tr><td>1035</td><td><code>round1 chunk out of order</code></td><td>Chunk order error</td></tr><tr><td>1036</td><td><code>jpake round1 failed</code></td><td>J-PAKE Round1 failed</td></tr><tr><td>1037</td><td><code>round1 response prepare failed</code></td><td>Preparing Round1 response chunks failed</td></tr><tr><td>1040</td><td><code>invalid step</code></td><td>J-PAKE Round2 step error</td></tr><tr><td>1041</td><td><code>jpake round2 failed</code></td><td>J-PAKE Round2 failed</td></tr><tr><td>1045</td><td><code>invalid step</code></td><td>Session nonce phase step error</td></tr><tr><td>1046</td><td><code>session nonce failed</code></td><td>Session nonce exchange failed</td></tr><tr><td>1047</td><td><code>cipher envelope required</code> / <code>secure channel required</code></td><td>Envelope or channel missing in the session state</td></tr><tr><td>1050</td><td><code>payload too large</code></td><td>Plaintext write too long</td></tr><tr><td>1051</td><td><code>invalid secure json</code></td><td>JSON invalid in secured mode</td></tr><tr><td>1060</td><td><code>secure encrypt failed</code></td><td>Encrypting the read characteristic response failed</td></tr><tr><td>1061</td><td><code>secure auth required</code></td><td>Read characteristic requires secured authentication first</td></tr><tr><td>1080 and up</td><td>dynamic English</td><td>Specific errors from the lower security module; use what the device returns</td></tr></tbody></table>

### 4. HTTP / HTTPS fixed error codes (2000s)

<table><thead><tr><th width="114.2222900390625">code</th><th>msg</th><th>Description</th></tr></thead><tbody><tr><td>2000</td><td><code>use_https</code></td><td>Policy requires HTTPS (port 80 returns 403)</td></tr><tr><td>2001</td><td><code>need token</code></td><td>A session token is required</td></tr><tr><td>2002</td><td><code>invalid token</code></td><td>Token invalid or expired</td></tr><tr><td>2003</td><td><code>wrong password</code></td><td>Sign-in password wrong</td></tr><tr><td>2004</td><td><code>password too long</code></td><td>Sign-in password too long (limit 16)</td></tr><tr><td>2005</td><td><code>need signin</code></td><td>Sign in first</td></tr><tr><td>2006</td><td><code>no password</code></td><td>No Web password set (status hint)</td></tr><tr><td>2007</td><td><code>no password set</code></td><td>No Web password set (sign-in case)</td></tr><tr><td>2008</td><td><code>missing newpass</code></td><td>New password parameter missing</td></tr><tr><td>2009</td><td><code>bad newpass length</code></td><td>New password length invalid (1 to 16)</td></tr><tr><td>2010</td><td><code>old password wrong</code></td><td>Old password wrong</td></tr><tr><td>2011</td><td><code>nvs save failed</code></td><td>Saving the Web password failed</td></tr><tr><td>2012</td><td>log file not found (Chinese msg)</td><td>Log file does not exist</td></tr><tr><td>2020</td><td><code>wifi not available!</code></td><td>No Wi-Fi; cannot download the remote page</td></tr><tr><td>2021</td><td><code>Error on HTTP request!</code></td><td>Remote HTTP request failed</td></tr><tr><td>2022</td><td><code>Error!</code></td><td>Opening or writing the local page file failed, or another update error</td></tr><tr><td>2023</td><td><code>download error!</code></td><td>Remote page download interrupted</td></tr><tr><td>2030</td><td><code>No text received.</code></td><td>Certificate upload received no body</td></tr><tr><td>2040</td><td><code>No data received</code></td><td><code>/save-config</code> received no body</td></tr><tr><td>2041</td><td><code>payload too large</code></td><td><code>/save-config</code> body too long</td></tr><tr><td>2050</td><td><code>No data received</code></td><td><code>/schedule</code> received no body (relay)</td></tr><tr><td>2051</td><td><code>payload too large</code></td><td><code>/schedule</code> body too long (relay)</td></tr><tr><td>2060</td><td><code>No data received</code></td><td><code>/switch-config</code> received no body</td></tr><tr><td>2061</td><td><code>payload too large</code></td><td><code>/switch-config</code> body too long</td></tr><tr><td>2062</td><td><code>No data received</code></td><td><code>/switch-config</code> lacks <code>configType</code> / <code>cmd</code></td></tr><tr><td>2070</td><td><code>bad json</code></td><td><code>/save-config</code> JSON cannot be parsed</td></tr><tr><td>2071</td><td><code>bad json</code></td><td><code>/schedule</code> JSON cannot be parsed</td></tr><tr><td>2072</td><td><code>bad json</code></td><td><code>/switch-config</code> JSON cannot be parsed</td></tr><tr><td>2080</td><td><code>use HTTP :80 multipart POST /upload</code></td><td>Upload endpoint misused on HTTPS</td></tr><tr><td>2081</td><td><code>file open failed</code></td><td>Opening the certificate file failed</td></tr><tr><td>2090</td><td><code>path not on HTTPS API</code></td><td>Path or method does not exist on HTTPS</td></tr><tr><td>2091</td><td><code>html not found</code></td><td>No web assets on the device</td></tr><tr><td>2095</td><td><code>Unknown status!</code></td><td>OTA status not recognized</td></tr><tr><td>2100</td><td><code>Error password length!</code></td><td>BLE password too long</td></tr><tr><td>2101</td><td><code>Old password error!</code></td><td>BLE old password wrong</td></tr><tr><td>2102</td><td><code>Error name length!</code></td><td>Device name too long</td></tr><tr><td>2110</td><td><code>Product update failure!</code></td><td>Online upgrade verify or write failed</td></tr><tr><td>2111</td><td><code>HTTP get failed!</code></td><td>Online upgrade download failed</td></tr></tbody></table>

### 5. MQTT and WebSocket fixed error codes

MQTT fixed codes (3000s; only in the legacy response `{"result":"failed",...}`; failures in the unified format use "3000 + s" from Section 2):

<table><thead><tr><th width="122">code</th><th>event</th><th>Description</th></tr></thead><tbody><tr><td>3001</td><td><code>rdata</code></td><td>Publishing the data report failed</td></tr><tr><td>3002</td><td><code>wint</code></td><td>Writing the report interval failed</td></tr><tr><td>3010</td><td><code>switch-config</code></td><td>Switch-extension configuration missing type (relay)</td></tr><tr><td>3011</td><td><code>wifi</code></td><td>Wi-Fi configuration failed</td></tr></tbody></table>

WebSocket (4000s, `event` is `error`):

<table><thead><tr><th width="113.111083984375">code</th><th>msg</th><th>Description</th></tr></thead><tbody><tr><td>4000</td><td><code>payload too large</code></td><td>A single frame is over the length limit</td></tr><tr><td>4001</td><td><code>invalid json</code></td><td>The message is not a JSON object</td></tr><tr><td>4002</td><td><code>json parse error</code></td><td>JSON syntax error</td></tr><tr><td>4003</td><td><code>invalid cmd</code></td><td>Command field missing or empty</td></tr></tbody></table>

Business commands that go through the unified parser get `code` as "4000 + s" from Section 2.

### 6. Collisions and how to tell them apart

Configuration subcodes run from 1 to 53, and the fixed codes in each channel range reuse those numbers. The same `code` can therefore mean two things, for example:

<table><thead><tr><th width="110.8887939453125">code</th><th>Meaning A (fixed error)</th><th>Meaning B (configuration subcode)</th></tr></thead><tbody><tr><td>1014</td><td>BLE secured <code>plain json invalid</code></td><td><code>functionMap error</code></td></tr><tr><td>1015</td><td>BLE secured <code>missing cmd</code></td><td><code>unknow cmd</code></td></tr><tr><td>1020</td><td>BLE <code>version failed</code></td><td><code>Error wifi reset in progress</code></td></tr><tr><td>1021</td><td>BLE <code>invalid step</code> (reset)</td><td><code>Error mqtt data empty!</code></td></tr><tr><td>2002</td><td>HTTP <code>invalid token</code></td><td><code>Error password length!</code></td></tr><tr><td>2003</td><td>HTTP <code>wrong password</code></td><td><code>auth error</code></td></tr><tr><td>2040</td><td>HTTP <code>/save-config</code> has no body</td><td><code>bleota err write</code></td></tr><tr><td>2051</td><td>HTTP <code>/schedule</code> body too long</td><td>SRS <code>illegal cmd</code></td></tr></tbody></table>

What to do:

1. Use `event` to know which command or endpoint the response belongs to.
2. Match the English `msg`; do not rely on `code` alone.
3. Different channels use different `code` ranges, so they never collide with each other.

### 7. Related pages

* The commands and their success responses are in the Business Command Reference; its Section 6 lists only the common business errors.
* How each channel returns errors: HTTP, MQTT, WebSocket.
* English `msg` values added by newer firmware: use what the device returns.
