"Credit balance is too low" returned for unrelated root causes

[rmalve]

Describe the bug

The Anthropic API returns the exact string "Credit balance is too low" for at least three distinct root causes, making it impossible to diagnose the underlying condition without trial-and-error:

1. Actual credit balance depletion.
2. Requested model requires a higher usage tier than the account
   holds.
3. The API key is valid and the associated account has cleared
   credits, but the key is orphaned/stale — authenticates successfully
   but is no longer authorized to bill against an active account.

Case 3 is the hardest to debug because the key authenticates, the account has cleared credits, the workspace has an adequate spend limit, and yet every request is rejected at preflight (sub-200ms duration, zero tokens billed) with the "credit balance" message. Rotating the key to a freshly minted one on the same account resolves it immediately.

To Reproduce

Steps to reproduce the behavior:

1. Create an API key on the Anthropic Console and store it as a
   GitHub repo secret named ANTHROPIC_API_KEY
2. Through some path (workspace reconfiguration, billing migration,
   or unknown server-side state change), the key becomes orphaned —
   externally not visible
3. Fund the account with credits, raise the workspace spend limit,
   and trigger any workflow run that uses
   anthropics/claude-code-action@v1
4. The action fails with SDK execution error: Error: Claude Code
   returned an error result: Credit balance is too low despite the
   account balance showing non-zero
5. Confirm account is healthy by running a direct POST /v1/messages
   from a local terminal using a freshly minted key on the same account
   — request succeeds with a 200 OK within seconds
6. Overwrite the GitHub secret with the freshly minted key and
   re-run the action — it now succeeds

Reliable repro of the orphaned-key state itself is difficult because the conditions causing it are not externally visible. However, the key-rotation fix is deterministic, which confirms case 3 exists as a distinct failure mode.

Expected behavior

The API should return distinct, actionable error codes for the three distinct conditions. For the orphan-key case specifically, a message like "This API key is no longer authorized to bill against an active account. Please create a new key." would collapse hours of debugging into a single-step fix.

More broadly: the current conflation sends users down unnecessary debugging paths — checking balance, topping up credits, raising workspace limits, investigating tiers, switching models — before they try key rotation, which is typically the last thing attempted because it feels like a shot in the dark.

Workflow yml file

  name: Claude Code

  on:
    issue_comment:
      types: [created]
    pull_request_review_comment:
      types: [created]
    issues:
      types: [opened, assigned]
    pull_request_review:
      types: [submitted]

  jobs:
    claude:
      if: |
        (github.event_name == 'issue_comment' &&
  contains(github.event.comment.body, '@claude')) ||
        (github.event_name == 'pull_request_review_comment' &&        
  contains(github.event.comment.body, '@claude')) ||
        (github.event_name == 'pull_request_review' &&
  contains(github.event.review.body, '@claude')) ||
        (github.event_name == 'issues' &&
  (contains(github.event.issue.body, '@claude') ||
  contains(github.event.issue.title, '@claude')))
      runs-on: ubuntu-latest
      permissions:
        contents: write
        pull-requests: write
        issues: write
        id-token: write
        actions: read
      steps:
        - name: Checkout repository
          uses: actions/checkout@v6
          with:
            fetch-depth: 1

        - name: Run Claude Code
          id: claude
          uses: anthropics/claude-code-action@v1
          with:
            anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}       
            settings: |
              {
                "env": {
                  "ANTHROPIC_MODEL": "claude-haiku-4-5-20251001"      
                }
              }

API Provider

[x] Anthropic First-Party API (default)
[ ] AWS Bedrock
[ ] GCP Vertex

Additional context

• Failing run (stale key): /actions/runs/24478755406 — first attempt reported { "duration_ms": 187, "total_cost_usd": 0, "is_error": true } and the SDK error was Credit balance is too low.
• Successful run: the same run re-executed after the ANTHROPIC_API_KEY secret was overwritten with a freshly minted key on the same account, no other variables changed.
• Account state when the bug was encountered: Tier 1, $5 cleared credits, workspace spend limit of $5, single workspace, requested model was Haiku 4.5 (universally accessible at all tiers).
• Direct POST https://api.anthropic.com/v1/messages from PowerShell using a freshly minted key on the same account returned 200 OK within seconds for the same model, definitively proving the account was capable of spending. Only the stale key behaved as though it wasn't.
• GitHub repo secrets are write-only, so users cannot verify what value is stored in ANTHROPIC_API_KEY. Diagnosis of this failure mode requires overwrite-and-retest, which is typically the last approach tried.
• This bug is arguably an API concern rather than an action concern, but the action is the highest-visibility
  surface where users hit it, because secret introspection is blocked there in a way it isn't for local development.
• Total debugging time from first failure to root cause: approximately 1.5 hours, driven almost entirely by the misleading error string sending me through balance → workspace limits → tier access → model selection before trying key rotation.