Anthropic API permission_error (HTTP 403): 5 causes in diagnostic order

HTTP 403 from the Anthropic API means your key is valid — the API recognized your authentication — but the specific action you're requesting is not permitted for your key, account tier, or workspace configuration. This is different from a 401 (bad key) and requires a different set of checks. This page covers the five causes in the order you should diagnose them.

What the error looks like

HTTP/1.1 403 Forbidden
{
  "type": "error",
  "error": {
    "type": "permission_error",
    "message": "Your API key does not have permission to use the specified resource."
  }
}

The message field varies slightly depending on the specific restriction. You may also see messages referencing model access, beta feature requirements, or workspace policy. In the Anthropic Python SDK this raises an anthropic.PermissionDeniedError. In the Node SDK it's a PermissionDeniedError.

Cause 1: Model not available at your API tier

Anthropic gates access to certain models — in particular Claude Opus — behind API usage tiers. New accounts or accounts below the spend threshold cannot call high-tier models, even with a valid API key.

To check your current tier: go to console.anthropic.com/settings/billing and look at the "Usage tier" section. Tier 1 (new accounts) does not have access to Opus. Tier 2 and above gain progressively broader model access.

Fix: use a model you have access to (claude-haiku-4-5 and claude-sonnet-4-5 are accessible at lower tiers). To unlock Opus, meet the tier threshold requirements — typically a combination of time using the API and cumulative spend. You cannot pay to jump tiers immediately; the progression is automatic as you use the API.

Current tier access by model (as of June 2026 — verify in Anthropic's docs as this changes):

Cause 2: Beta feature without the required header

Anthropic releases some capabilities in beta behind the anthropic-beta request header. If you call an endpoint or use a parameter that requires a beta flag without providing the header, you receive a 403.

Common beta features and their required header values:

Fix: add the anthropic-beta header with the correct value for the feature you're using. These values are documented in Anthropic's feature-specific documentation pages. If using the official SDK, set it via the extra_headers parameter:

# Python SDK
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-5-20251022",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[...],
    extra_headers={"anthropic-beta": "interleaved-thinking-2025-05-14"}
)

Cause 3: Workspace API key with model restrictions

Anthropic workspace admins can create API keys restricted to specific models. If your key was provisioned by an org admin with model allowlist or denylist settings, requests to restricted models return 403 regardless of your account tier.

How to check: go to console.anthropic.com/settings/keys. If you see a "Restrictions" field on your key showing specific models, that is the active constraint.

Fix: either request a new key from your admin with the models you need, or ask the admin to update the existing key's restrictions. If you're the admin: edit the key in the console and adjust the model access settings.

Cause 4: Key created before a feature was available (stale key permissions)

Occasionally, API keys created before Anthropic launched a specific feature or tier may not automatically inherit access to that feature. This is rare but has been reported for some enterprise features and early beta programs.

Fix: generate a new API key from your current account. New keys reflect the current state of your account's entitlements. If the new key still returns 403 for the same request, the issue is the account tier (Cause 1) rather than a stale key.

Cause 5: Organizational policy or IP allowlist restriction

Enterprise Anthropic accounts may have organizational controls in place — IP allowlists, geographic restrictions, or service account policies — that block specific API key usage from certain environments. This typically manifests as a 403 that appears in some environments (a development machine, a cloud provider's IP range) but not others.

How to diagnose: test the same key from a different network or environment. If the request succeeds elsewhere, the issue is a network-level or organizational restriction rather than the key itself.

Fix: work with your organization's Anthropic admin to adjust IP allowlists, or use an environment that is within the allowed network policy.

Quick diagnostic checklist

1. Check the exact message field in the error JSON — it often names the specific resource you lack access to.
2. Does the error occur with a different, lower-tier model? If yes → Cause 1 (model tier).
3. Does the request use a beta parameter (thinking, betas, extended max_tokens)? If yes → Cause 2 (missing beta header).
4. Was your key created by an admin? If yes → Cause 3 (workspace restriction).
5. Does the error only occur from a specific environment? If yes → Cause 5 (network policy).
6. None of the above → regenerate the key (Cause 4).

Related

• Claude API 401 authentication_error: 5 causes & fixes
• Anthropic API authentication error: step-by-step fix
• OpenAI API organization not found error: fix

Last updated June 8, 2026. API tier thresholds and beta feature header values are subject to change — verify against current Anthropic documentation.