Summary

Problem

When using OpenClaw with a Claude Max plan ($100/mo subscription), hitting the plan's rate limits causes Anthropic's API to return HTTP 402 (payment required) instead of HTTP 429 (rate limited).

OpenClaw correctly interprets 402 as a billing error and posts a warning to the channel:

⚠️ API provider returned a billing error — your API key has run out of credits or has an insufficient balance.

This is misleading for Max plan users who have active credits and valid billing. The actual issue is a temporary rate limit, not insufficient funds.

Context

• Plan: Claude Max ($100/mo) with Extra Usage enabled
• Extra Usage balance: $41.36 (well above zero)
• Extra Usage monthly limit: $50
• Behavior: Error fires repeatedly during normal usage, especially when image analysis or high-traffic Slack channels are active

Expected Behavior

OpenClaw should either:

1. Recognize that 402 from Anthropic on a Max plan may indicate rate limiting rather than billing exhaustion, and display a different message
2. Provide a config option to suppress or reclassify 402 errors for Max plan users
3. Add retry-after behavior for 402s similar to 429 handling

Environment

• OpenClaw version: 2026.2.6-3
• Model: claude-opus-4-6 / claude-sonnet-4-6
• Channels: Slack (socket mode), WhatsApp
• Auth: Max plan token

Steps to reproduce

1. Subscribe to Anthropic Max plan (claude.ai)
2. Use OpenClaw with Anthropic API key
3. Hit the Max plan's rate limit (e.g. heavy usage within the 5-hour window)
4. Anthropic returns HTTP 402 instead of 429
5. OpenClaw displays: "⚠️ API provider returned a billing error — your API key has run out of credits or has an insufficient balance"
6. No actual billing issue exists — credits/balance are fine, it's a rate limit

Expected behavior

OpenClaw should recognize Anthropic 402 as a rate limit (retry/backoff), not a billing error.

Actual behavior

OpenClaw treats the HTTP 402 as a fatal billing error — displays a scary "run out of credits" warning and stops the request. No retry or backoff is attempted.

OpenClaw version

2026.2.6-3

Operating system

macOS Sonoma 14.8.2

Install method

No response

Logs, screenshots, and evidence

Impact and severity

Additional information

No response