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) |
Empty/missing required field (apiKey, refreshToken) | 422 | Fails validation before any lookup |
| Invalid, expired, or already-rotated/revoked refresh token | 401 | Refresh and revoke both return 401 for a token that can no longer be used; revoking an already-revoked token is the one exception — it still returns success (idempotent) |
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.