Authentication Errors
Authentication and authorization problems can include an invalid or inactive
API key, an unusable access token, an invalid, expired, or already-rotated/
revoked refresh token, or an invalid X-SubAccount-Id.
Verified status codes
| Situation | Status | Notes |
|---|---|---|
| Invalid or inactive API key | 401 | Token exchange (POST /api/v1/auth/token) |
Missing, empty, or whitespace-only required field (apiKey, refreshToken) | 422 | Fails validation before any lookup, so it is never a 401 |
| Unrecognized, expired, or already-rotated/revoked refresh token | 401 | Refresh answers 401 for a token that can no longer be used. Revoke has one documented exception: a token Mailhub has already revoked — by an earlier revoke or by refresh rotation — answers 200 again. That is the bounded behaviour, not blanket idempotency; a token Mailhub does not recognize still answers 401 |
Malformed X-SubAccount-Id (not a GUID) | 400 | |
X-SubAccount-Id for a sub-account that doesn't exist or belongs to another account | 404 | |
X-SubAccount-Id for a sub-account that is inactive | 409 |
Recover safely
Confirm that the correct environment credential is active and that the Authorization value is present without logging it. When the access token is no longer usable, attempt one refresh; if it fails, stop and authenticate again. Do not treat every authentication failure as token expiry and never create an infinite refresh loop.
See Authentication for the token flow.