Significant-Gravitas/AutoGPT · error · HTTPException

Insufficient balance to execute the agent. Please top up you

Error message

Insufficient balance to execute the agent. Please top up your account.

What it means

Raised (402 Payment Required) by POST /graphs/{graph_id}/execute/{graph_version} when dry_run is false and the user's credit balance (credit_model.get_credits) is <= 0. Execution costs credits, so the API refuses to schedule a run the user cannot pay for. dry_run requests bypass the check entirely.

Source

Thrown at autogpt_platform/backend/backend/api/features/v1.py:1985

)
async def execute_graph(
    graph_id: str,
    user_id: Annotated[str, Security(get_user_id)],
    ctx: Annotated[RequestContext, Security(get_request_context)],
    inputs: Annotated[dict[str, Any], Body(..., embed=True, default_factory=dict)],
    credentials_inputs: Annotated[
        dict[str, CredentialsMetaInput], Body(..., embed=True, default_factory=dict)
    ],
    source: Annotated[GraphExecutionSource | None, Body(embed=True)] = None,
    graph_version: Optional[int] = None,
    preset_id: Optional[str] = None,
    dry_run: Annotated[bool, Body(embed=True)] = False,
) -> execution_db.GraphExecutionMeta:
    if not dry_run:
        credit_model = await get_credit_model(user_id, ctx.org_id)
        current_balance = await credit_model.get_credits(user_id)
        if current_balance <= 0:
            raise HTTPException(
                status_code=402,
                detail="Insufficient balance to execute the agent. Please top up your account.",
            )

    try:
        result = await execution_utils.add_graph_execution(
            graph_id=graph_id,
            user_id=user_id,
            inputs=inputs,
            preset_id=preset_id,
            graph_version=graph_version,
            graph_credentials_inputs=credentials_inputs,
            dry_run=dry_run,
            organization_id=ctx.org_id,
            team_id=ctx.team_id,
        )
        # Record successful graph execution
        record_graph_execution(graph_id=graph_id, status="success", user_id=user_id)

View on GitHub (pinned to 9c8bb5550f)

Solutions

1. Top up the account via the credits/checkout endpoint, then retry the execution.
2. If you only want to validate the graph, call with dry_run=true to skip the balance gate.
3. In the UI, check the balance before showing the Run button and deep-link to the top-up flow on 402.

Example fix

// before
await api.executeGraph(graphId, { inputs });

// after
const status = await api.getCreditStatus();
if (status.credits <= 0) {
  window.location.href = '/credits'; // top-up flow
} else {
  await api.executeGraph(graphId, { inputs });
}

const { credits } = await api.getUserCreditStatus();
if (credits <= 0) {
  router.push('/credits?topup=1&next=' + encodeURIComponent(currentPath));
  return;
}
await api.executeGraph(graphId, { inputs });

const canAffordRun = (balance: number) => balance > 0;

catch (e) { if (e.response?.status === 402) { openTopUpDialog(); } else throw e; }

When it happens

Trigger: A normal (non-dry-run) agent execution by a user with zero or negative credits — new users who never topped up, users who exhausted their balance, or refunds/holds driving the balance to 0.

Common situations: First-time users hitting Run before claiming free credits or topping up; long-running agents draining balance mid-session so the next run is rejected; trial credits expiring.

Related errors

• Insufficient balance of ${current_balance / 100}, where this
• str(e)
• start and end query params are required
• str(exc)
• Execution not found or not in QUEUED status

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