insufficient_credits

The insufficient_credits error occurs when the principal billed for a cloud agent run has no remaining credits to charge against.

On self-serve plans (Build, Max, Business), the billed principal depends on how the run was triggered:

• User-triggered runs draw from the triggering user’s plan-included credits first, then the team’s shared add-on credit pool.
• Agent API key and scheduled runs draw from the team owner’s plan-included credits first, then the team’s shared add-on credit pool.

When both are depleted and auto-reload is off, new runs return this error. On Enterprise plans, runs draw from the team-scoped credit pool per your contract — contact your account manager when the pool is exhausted.

---

Details

• HTTP Status: 403 Forbidden
• Retryable: No
• Task State: FAILED

---

When does this occur?

This error is returned when:

• A user-triggered run runs out of the user’s plan-included credits and the team’s shared add-on credit pool.
• An agent API key or scheduled run runs out of the team owner’s plan-included credits and the team’s shared add-on credit pool.
• Auto-reload is off, or auto-reload is on but the team-wide monthly spend cap has been reached.

For the full waterfall, see How are cloud agent runs on team plans billed when no individual user triggered them? in the Pricing FAQs.

---

Example response

{
  "type": "/reference/api-and-sdk/troubleshooting/errors/insufficient-credits/",
  "title": "The principal billed for this run has no remaining credits. Purchase add-on credits or raise the team-wide spend cap to continue.",
  "status": 403,
  "instance": "/api/v1/agent/tasks",
  "retryable": false
}

---

How to resolve

The fix depends on which principal was billed.

For user-triggered runs (your plan credits and the team’s add-on pool were exhausted):

1. Purchase add-on credits in Settings > Billing and usage — any active member’s purchase tops up the team’s shared pool — or wait for your monthly credits to refresh.
2. Alternatively, enable auto-reload, subject to your team’s monthly spend cap.
3. Retry the failed operation.

For agent API key or scheduled runs (the owner’s plan credits and the team’s add-on pool were exhausted):

1. Top up the team’s shared pool by purchasing add-on credits, or wait for the owner’s monthly credits to refresh.
2. If auto-reload is on but the team-wide spend cap was reached, an admin can raise the cap in Settings > Billing and usage.
3. Retry the failed operation.

Any active team member can top up the shared pool; raising the spend cap or changing auto-reload requires a team admin.

---

Related

• Access, billing, and identity permissions — Credit billing for individual user runs and agent API key runs.
• Add-on credits — Purchase additional credits and configure auto-reload.
• Platform credits — The third credit bucket alongside AI credits and compute credits.
• Cloud Agents Overview — Billing and plan requirements for cloud agents.