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 any applicable cloud agent credit grant, then the triggering user’s plan-included monthly Warp credits, then the team’s shared add-on credit pool. Cloud agent grants apply only to user-triggered cloud runs.
• Agent API key and scheduled runs draw from the team owner’s plan-included monthly Warp credits first, then the team’s shared add-on credit pool.

When those sources 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 any applicable cloud agent credit grant, the user’s plan-included monthly Warp 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 monthly Warp 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 cloud agent runs use credits.

---

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 applicable grant, plan-included monthly Warp credits, and the team’s add-on pool were exhausted):

1. Purchase add-on credits in Settings > Billing and usage, or wait for your monthly credits to refresh. Any active member’s purchase tops up the team’s shared pool.
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-included monthly Warp 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.