TL;DR —
401 means re-exchange or refresh your token and retry once; 403 means fix the key’s scope or the outlet_id you sent — neither is safe to retry as-is.When this happens
- Your access token has passed its 300-second TTL —
401 urn:radiumone:gateway:token-expired. - Your token failed verification (malformed, wrong signature) —
401 urn:radiumone:gateway:token-invalid. - Your token is valid but lacks the scope the endpoint requires —
403 urn:radiumone:auth:insufficient-scope. - Your key is bound to one outlet and the request named a different
outlet_id—403 urn:radiumone:auth:outlet-binding-violation.
What you see
What to do
1
Re-exchange or refresh, then retry once
Access tokens are short-lived by design (300 seconds) — expiry during normal use is expected, not a bug. Exchange your key for a fresh token (API reference), or rotate your refresh token if you have one (API reference):Retry the original call once with the new token. If it fails again with the same error, don’t loop — treat it as a configuration problem instead.
2
Fix the key's scope for insufficient-scope
403 insufficient-scope means the token you exchanged doesn’t carry the scope the call needs. Request a key scoped for the operation — see Authentication: scopes and least-privilege keys — rather than retrying with the same key.3
Send the right outlet, or omit it
403 outlet-binding-violation means the outlet_id on the request doesn’t match your key’s bound outlet. Omit outlet_id to use the key’s own outlet, or send the correct one.Test it
See Test your integration and Sandbox and API keys for key setup and scope configuration in sandbox.Related
Authentication
Exchange a key for a token, and refresh it before it expires.
Sandbox and API keys
Key types, scopes, and where to get sandbox credentials.
Payment operation errors
The full URN catalog for auth and validation errors.