Errors
auth_token_mode_mismatch
401 — the token resolved but its declared mode (test or live) does not match the host or Matter-Mode header on the request.
Last updated
Cause
Every Matter token is bound to exactly one mode — test or live — at the moment it is issued. The mode is encoded in the token prefix (sk_test_* vs sk_live_*) and again in the token row. Matter rejects requests where the token's mode does not match the request's mode, which can be derived from the host (api.test.mattermode.com vs api.mattermode.com) or the Matter-Mode header.
This is a hard boundary that prevents accidental cross-mode reads or writes: a test-mode token cannot read live data, and a live-mode token cannot mutate test fixtures. The error is intentionally distinct from auth_token_invalid so that a misrouted CI run or local-vs-prod environment confusion can be diagnosed without searching the wrong audit log.
Fix
- Confirm which mode the caller intends. Test mode is for fixtures, mock filings, and CI; live mode touches real registries and real money.
- If the host is wrong, change the base URL. Use
api.test.mattermode.comfor test andapi.mattermode.comfor live. - If the host is correct but the token is wrong, fetch the matching-mode token from your secrets manager. Test and live secrets are stored as separate entries; never share one across modes.
- Never coerce by setting
Matter-Modeto override the token's mode — Matter ignores the header when it conflicts with the token, and the error persists until the token itself matches.
Related codes
auth_token_invalid— the token doesn't resolve at all.not_found_in_mode— the token mode matches but the referenced resource lives in the other mode.