{"record":{"id":"f32e53a2da58b6fb","repo":"Significant-Gravitas/AutoGPT","slug":"insufficient-balance-to-execute-the-agent-please","errorCode":null,"errorMessage":"Insufficient balance to execute the agent. Please top up your account.","messagePattern":"Insufficient balance to execute the agent\\. Please top up your account\\.","errorType":"http","errorClass":"HTTPException","httpStatus":402,"severity":"error","filePath":"autogpt_platform/backend/backend/api/features/v1.py","lineNumber":1985,"sourceCode":")\nasync def execute_graph(\n    graph_id: str,\n    user_id: Annotated[str, Security(get_user_id)],\n    ctx: Annotated[RequestContext, Security(get_request_context)],\n    inputs: Annotated[dict[str, Any], Body(..., embed=True, default_factory=dict)],\n    credentials_inputs: Annotated[\n        dict[str, CredentialsMetaInput], Body(..., embed=True, default_factory=dict)\n    ],\n    source: Annotated[GraphExecutionSource | None, Body(embed=True)] = None,\n    graph_version: Optional[int] = None,\n    preset_id: Optional[str] = None,\n    dry_run: Annotated[bool, Body(embed=True)] = False,\n) -> execution_db.GraphExecutionMeta:\n    if not dry_run:\n        credit_model = await get_credit_model(user_id, ctx.org_id)\n        current_balance = await credit_model.get_credits(user_id)\n        if current_balance <= 0:\n            raise HTTPException(\n                status_code=402,\n                detail=\"Insufficient balance to execute the agent. Please top up your account.\",\n            )\n\n    try:\n        result = await execution_utils.add_graph_execution(\n            graph_id=graph_id,\n            user_id=user_id,\n            inputs=inputs,\n            preset_id=preset_id,\n            graph_version=graph_version,\n            graph_credentials_inputs=credentials_inputs,\n            dry_run=dry_run,\n            organization_id=ctx.org_id,\n            team_id=ctx.team_id,\n        )\n        # Record successful graph execution\n        record_graph_execution(graph_id=graph_id, status=\"success\", user_id=user_id)","sourceCodeStart":1967,"sourceCodeEnd":2003,"githubUrl":"https://github.com/Significant-Gravitas/AutoGPT/blob/9c8bb5550f446ba5d3046b78896578742495b3cf/autogpt_platform/backend/backend/api/features/v1.py#L1967-L2003","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Top up the account via the credits/checkout endpoint, then retry the execution.","If you only want to validate the graph, call with dry_run=true to skip the balance gate.","In the UI, check the balance before showing the Run button and deep-link to the top-up flow on 402."],"exampleFix":"// before\nawait api.executeGraph(graphId, { inputs });\n\n// after\nconst status = await api.getCreditStatus();\nif (status.credits <= 0) {\n  window.location.href = '/credits'; // top-up flow\n} else {\n  await api.executeGraph(graphId, { inputs });\n}","handlingStrategy":"validation","validationCode":"const { credits } = await api.getUserCreditStatus();\nif (credits <= 0) {\n  router.push('/credits?topup=1&next=' + encodeURIComponent(currentPath));\n  return;\n}\nawait api.executeGraph(graphId, { inputs });","typeGuard":"const canAffordRun = (balance: number) => balance > 0;","tryCatchPattern":"catch (e) { if (e.response?.status === 402) { openTopUpDialog(); } else throw e; }","preventionTips":["Check balance before enabling the Run button; poll it for long sessions since balance drains mid-run.","Use dry_run=true while iterating on graph structure to avoid burning credits and hitting the gate.","Map 402 to the top-up flow with a return URL so users can resume the run after paying."],"tags":["credits","payments","execution","http-402","balance"],"backgroundTag":null,"analyzedSha":"9c8bb5550f446ba5d3046b78896578742495b3cf","analyzedAt":"2026-08-14T17:17:21.957Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}