Questions · Updated 2026-09-28

What does agent_budget_exceeded mean?

agent_budget_exceeded means this API key has spent its budget_per_period for the current period, and the send was refused. GET /usage returns consumed_in_period, remaining and resets_at for the key; raising the budget is PATCH /limits/keys/{id} by a person, and the key cannot raise its own.

agent_budget_exceeded means the key you are sending with has spent its budget_per_period for the current period, and the send was refused. No retry passes before the period resets, so retryable is false. The ceiling was set on this key with PATCH /limits/keys/{id}; GET /usage says what the key has consumed and when the period resets. Its error catalogue message is "Key budget for the current period is exhausted."

The fix, and the message on the wire

The catalogue fix says "Wait for the period to reset — get_agent_budget and GET /limits/keys/:id both say when. Raising a budget is a person’s decision, made in the console; a key cannot raise its own." On the wire the message is more specific than the catalogue default: it names how many messages the key has used of its budget, and which period that budget covers.

Reading the budget

GET /limits/keys/{id} returns budget_per_period, period (hourly, daily or monthly), consumed_in_period and period_started_at; the reset follows from the last two. GET /usage returns one row per key with budget_per_period, consumed_in_period, remaining, used_percent and resets_at, the moment the budget refills. Its summary is "This period usage, per key: budget, consumed, remaining, rate window, last used. The bill, made legible." Both are management endpoints, so they take a full_access key. Over MCP, get_agent_budget is the call the fix names.

curl -sS -X GET https://api.agentisend.com/usage \
  -H "Authorization: Bearer $AGENTISEND_API_KEY"
200
{
  "account": {},
  "keys": [],
  "period_started_at": "2026-09-04T09:14:00Z"
}
Response

A webhook heard about this before it happened. Budgets and the kill switch says limit.warning fires on the way up, before a key budget is spent, and limit.exceeded fires the first time the budget refuses a send, once per key per period, carrying resets_at. Subscribe to both with POST /webhooks.

Retrying, and the neighbouring ceilings

retryable is false, so stop and wait for resets_at. The ceiling is checked before every send, so no retry inside the period passes. Do not ask the key to raise itself: the summary of PATCH /limits/keys/{id} is "Set or clear this key’s period budget and per-minute ceiling. An API key may lower its own; raising one is a person’s decision, made in the console." A key that sends a higher budget_per_period is answered human_action_required; a person raises it in the console. A different key has a budget of its own, and switching keys to keep sending is the behaviour the ceiling exists to stop.

Two neighbouring codes are different ceilings. plan_limit_reached is the account's plan inclusion, spent across every key, and its reset date is in that error. rate_ceiling_exceeded is this key's per-minute ceiling, rate_ceiling_per_minute on the same PATCH /limits/keys/{id}, and that one is retryable with retry_after_seconds.

Next