Significant-Gravitas/AutoGPT · error · InsufficientBalanceError

str(e)

Error message

str(e)

What it means

This is the HTTP 402 detail produced when `charge_for_direct_block_execution` raises `InsufficientBalanceError`: `str(e)` carries the billing message (typically the required credit amount vs. remaining balance). Direct external block executions are metered upfront; if the user's credit balance can't cover the block's cost, the request fails with Payment Required before execution.

Source

Thrown at autogpt_platform/backend/backend/api/external/v1/routes.py:117

    # consistent with chat / internal block / internal graph routes.
    await enforce_payment_paywall(auth.user_id)

    obj = backend.blocks.get_block(block_id)
    if not obj:
        raise HTTPException(status_code=404, detail=f"Block #{block_id} not found.")
    if obj.disabled:
        raise HTTPException(status_code=403, detail=f"Block #{block_id} is disabled.")

    user = await user_db.get_user_by_id(auth.user_id)
    if not user:
        raise HTTPException(status_code=404, detail="User not found.")

    try:
        await charge_for_direct_block_execution(
            user_id=auth.user_id, block=obj, input_data=data, source="external"
        )
    except InsufficientBalanceError as e:
        raise HTTPException(
            status_code=status.HTTP_402_PAYMENT_REQUIRED, detail=str(e)
        ) from e

    # Direct block execution has no graph; build a minimal ExecutionContext
    # carrying the caller's identity + timezone so blocks that depend on
    # those (e.g. time blocks) get correct data.
    execution_context = ExecutionContext(
        user_id=auth.user_id,
        user_timezone=get_user_timezone_or_utc(user.timezone),
    )

    output = defaultdict(list)
    async for name, data in obj.execute(data, execution_context=execution_context):
        output[name].append(data)
    return output


@v1_router.post(

View on GitHub (pinned to 9c8bb5550f)

Solutions

1. Top up the user's credit balance in the platform, then retry the execution.
2. Switch the block/model configuration to a cheaper option to fit the current balance.
3. Monitor balance via the platform's user/credit endpoints and alert before it hits zero for unattended automations.

Example fix

# before
POST /blocks/{llm_block_id}/execute  # 402 {"detail": "Insufficient balance: need 10, have 2"}

# after: top up credits, then retry
POST /blocks/{llm_block_id}/execute  # 200

balance = client.get("/users/me/credits").json()["balance"]
if balance < estimated_block_cost(block_id):
    raise InsufficientCredits(f"need ~{estimated_block_cost(block_id)}, have {balance}")

try:
    client.post(f"/blocks/{block_id}/execute", json=data)
except HTTPError as e:
    if e.response.status_code == 402:
        top_up_credits(min_amount=parse_needed(e.response.text))
        client.post(f"/blocks/{block_id}/execute", json=data)  # retry after top-up
    else:
        raise

When it happens

Trigger: POST `/blocks/{block_id}/execute` when the API key owner's credit balance is lower than the execution cost of the block (LLM blocks, metered API blocks).

Common situations: Exhausted free-tier credits on a hosted deployment; long-running automation draining balance mid-run; new expensive model selected on a block raising per-run cost.

Related errors

• Rate limit reset is not available (credit system is disabled
• Insufficient credits to reset your rate limit.
• Insufficient balance of ${current_balance / 100}, where this
• str(e)
• Copy failed: ${res.status}

AI-assisted analysis of Significant-Gravitas/AutoGPT@9c8bb5550f (2026-08-14). Data as JSON: /api/errors/ede78343f747e992. Report an issue: GitHub.