Errors
scope_tier_insufficient
403 — the operation is permitted by the token's resource scope but blocked by the token's tier ceiling.
Last updated
Cause
Matter classifies operations by tier — tier 1 (read-only metadata), tier 2 (single-resource writes), tier 3 (cross-resource sagas), tier 4 (entity-changing legal actions such as formation submission, dissolution, equity issuance). Every token carries a tier_max ceiling. When an operation's required tier exceeds the token's ceiling, Matter returns scope_tier_insufficient.
This is a separate axis from the resource-scope policy. A token can be granted the entities:* resource scope but still be capped at tier 2, in which case it can read and update an entity but cannot dissolve one — dissolution is tier 4. The two checks compose; both must pass.
Fix
- Read the operation's tier from the API reference. Each endpoint declares its
x-matter-tierin the spec. - Read the token's
tier_maxfromretrieveToken. - If the gap is legitimate, mint a higher-tier token bound to the principal who is authorised for that level of action. For tier 4 operations, the principal is almost always a natural person — agents are issued tier 3 ceilings by default and must be escalated explicitly.
- If the gap is accidental, fix the calling code to use the right token. Production systems should typically run several tokens at different tiers and route operations to the lowest-tier credential that can complete them.
Related codes
scope_denied— the resource scope itself excludes this verb.scope_resource_out_of_portfolio— the verb is allowed in general but not on this resource.state_authorisation_required— the operation needs an authorising Resolution in addition to a high-tier token.