Skip to main content
A call is rejected before it ever reaches business logic — your access token expired, was malformed, or doesn’t carry the scope or outlet the call needs.
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.

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.
Last modified on September 15, 2026