INVALID_API_KEY (401)
API key is missing, revoked, or malformed.
Common causes
• Missing Authorization header
• Revoked key
• Wrong environment key
Resolution
Regenerate a scoped key and retry with correct environment.
INSUFFICIENT_SCOPE (403)
API key does not have required permission scope.
Common causes
• Key missing entitlements:read
• Write attempted with read-only key
Resolution
Issue a key with minimum required scope for the endpoint.
RESOURCE_NOT_FOUND (404)
Requested entity does not exist in workspace.
Common causes
• Customer ID typo
• Cross-workspace identifier
Resolution
Verify resource IDs and workspace context.
FREE_TIER_CAP_EXCEEDED (402)
Free-tier monthly API cap reached; upgrade required to continue.
Common causes
• Free workspace exceeded its API call allowance
• Write request attempted after the cap
Resolution
Upgrade to a paid plan or wait for the next billing period.
RATE_LIMIT_EXCEEDED (429)
Request rate exceeded current allowance. A per-key burst limit applies only when your workspace's effective api_rate_limit_per_minute entitlement — its plan value, plus any approved override MonetizeKit has granted your workspace — is positive; absent or 0 means no burst limit, the limiter is skipped, and no X-RateLimit-* headers are sent. The one exception is a Free workspace over its monthly quota, whose reads are throttled to 20 requests/minute. Responses checked against a limit carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset; responses with no limit in force omit them.
Common causes
• Burst traffic
• Missing backoff logic
Resolution
Read X-RateLimit-Reset and retry after that reset time with jittered backoff.
For key/scope issues (INVALID_API_KEY, INSUFFICIENT_SCOPE), see the Authentication guide and the Auth and Permission Issues guide.