# Error Codes

Reference for common API failures and remediation steps.

<!-- docs-source -->
Source: https://learning.monetizekit.app/docs/troubleshooting/error-codes
<!-- /docs-source -->

### 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](/docs/getting-started/authentication) and the [Auth and Permission Issues guide](/docs/troubleshooting/auth-issues).