Omada portal authorization error codes
Every Omada JSON answer carries an errorCode. VoqadoWiFi records it on each failed attempt, so the number in Portal Health tells you which of the three authorization methods failed and why.
-1001 means the one time token expired; -1003 and -1005 mean the site or MAC did not match; -41009 and -41501 are transient cloud errors that are retried; -41010 means the device is not waiting in the portal state for the OpenAPI method. -1 and -3 mean already authorized and count as success.Causes, in the order to check them
1. The token method fails firstOmada
VoqadoWiFi always tries the standard hand off first: it returns the one time token to /portal/auth on your controller or TP-Link’s cloud. A rejected token, a redirect, or a 4xx answer moves on to the credential methods.
Portal Health shows the code from the last method tried. A failure with no credentials configured reads “Token-based auth failed and no operator/API credentials configured”.
Fix the token path first; it needs no stored password. The codes below say what to look at.
2. -1001: the token expiredOmada
Omada’s token is short lived. A guest who lingers on the form, or a phone that slept, returns an old token.
Failures cluster on long forms or on guests who opened the portal and came back to it later.
Keep the form short. A guest who rejoins gets a fresh token.
3. -1003 or -1005: the site or MAC did not matchOmada
The controller could not match the site or device in the request, most often because the portal URL carried its own query string, or the Site ID in the dashboard is wrong.
Read the portal URL in the controller and the Site ID on the location.
Paste the URL exactly as printed, and correct the Site ID.
4. -41009 or -41501: transient cloud errorsOmada
Brief instability on TP-Link’s cloud. The OpenAPI method retries once and the operator method up to three times before reporting it.
Occasional entries rather than every attempt.
Nothing, if it is occasional. If every attempt shows it, check TP-Link’s cloud status before changing settings.
5. -41010: not in the portal waiting state for OpenAPIOmada
The OpenAPI method could not find the device waiting for portal authorization. The integration moves on to the hotspot operator method when operator credentials exist.
Portal Health shows “OpenAPI auth returned -41010 and no operator credentials configured for v2 fallback”.
Add hotspot operator credentials for the location, or fix the token path so the fallback is not needed.
Reference
| Code or message | Meaning | What the integration does |
|---|---|---|
| -1, -3 | Device already authorized | Counts it as success |
| -1001 | Token expired | Tries credential methods if configured |
| -1003, -1005 | Site or MAC did not match | Tries credential methods if configured |
| -41009, -41501 | Transient cloud error | Retries, then reports |
| -41010 | Not in portal state for OpenAPI | Moves on to the operator method |
| Other non zero codes | Hard error from the controller | Reports it as controller |
| Controller ID missing | No omadacId for the cloud methods | Reports it as auth |
| v2 auth redirected | Operator session not accepted | Reports it as auth |
Questions
Which methods does the integration use on Omada?
Do I need OpenAPI or operator credentials at all?
Keep reading
Error kinds and codes on this page are the ones the VoqadoWiFi integration records, checked against the code on 7 October 2026.
See every authorization attempt
Portal Health in the free dashboard shows each guest login with its error kind and code. One location and 25 guest logins a month, no card.