Errors
op_rate_limit_exceeded
429 — the calling token has exceeded its short-window request rate; retry after the interval named in Retry-After.
Last updated
Cause
Matter applies a sliding-window request rate limit per token. The limit varies by token kind and account tier; the headers X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are emitted on every response so callers can self-throttle before hitting the wall. op_rate_limit_exceeded fires when the calling token submits a request after X-RateLimit-Remaining has reached zero.
The limit exists to protect platform stability and to keep noisy neighbours from impacting other tenants. It is not a quota — it does not consume monthly budget, and the window refills automatically once Retry-After elapses. Persistent rate-limit hits suggest a tight retry loop or a fan-out pattern that needs jittered backoff.
Fix
- Read the
Retry-Afterheader. Wait at least that many seconds before the next request from this token. - Implement exponential backoff with jitter for retries. A naive constant-delay retry on every 429 keeps the token stuck at the limit.
- Watch
X-RateLimit-Remainingand self-throttle when it dips. Calling at the limit's edge is fragile against bursts. - If the workload genuinely needs more headroom, request a higher tier from the dashboard rather than minting more tokens — splitting work across tokens to bypass the limit violates the platform terms.
Related codes
op_quota_exceeded— a monthly resource quota has been exhausted.op_service_degraded— the platform itself is throttling under load.