billing_error / payment_required

What the error looks like

{
  "type": "error",
  "error": {
    "type": "payment_required",
    "message": "Your credit balance is too low to make API requests. Please go to Plans & Billing to get more credits."
  }
}

HTTP status: 402. You may also see "type": "billing_error" in some account states.

Common causes

• Free-tier credits exhausted — new accounts get $5 of free credits; once spent, all calls return 402
• No payment method on file — account was never upgraded from the free tier
• Card declined or expired — Anthropic tried to charge and the card failed
• Hard spending limit reached — you set a monthly cap in the Console and crossed it
• Account suspended for billing — unpaid invoices or fraud hold

Fix: Add or update your payment method

1. Go to console.anthropic.com → Settings → Billing
2. Click Add payment method (Visa, Mastercard, Amex accepted)
3. Purchase a credit top-up ($5 minimum, or enable auto-recharge)
4. Retry your API call — the 402 will be gone immediately

Fix: Raise or remove your spending limit

If you have a spending cap set:

1. Go to Settings → Billing → Usage limits
2. Increase the monthly spend limit or disable it
3. Optionally set an alert threshold instead of a hard cap

Check your balance programmatically

import anthropic

client = anthropic.Anthropic()

# The SDK wraps 402 as anthropic.PaymentRequiredError
try:
    message = client.messages.create(
        model="claude-opus-4-5",
        max_tokens=1024,
        messages=[{"role": "user", "content": "Hello"}]
    )
except anthropic.PaymentRequiredError as e:
    print(f"Billing issue: {e}")
    print("Go to https://console.anthropic.com/settings/billing")

TypeScript / Node.js

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

try {
  const message = await client.messages.create({
    model: "claude-opus-4-5",
    max_tokens: 1024,
    messages: [{ role: "user", content: "Hello" }],
  });
} catch (error) {
  if (error instanceof Anthropic.PaymentRequiredError) {
    console.error("Billing issue — add credits at console.anthropic.com");
  }
}

Frequently Asked Questions

Related errors

• authentication_error (401) — invalid or missing API key
• permission_error (403) — key lacks required scopes
• rate_limit_error (429) — too many requests per minute