Credits and usage
Errors and limits
The typed errors a tool returns, what each one costs, and the rate limits.
When a tool cannot answer, it does not fail silently. It returns a typed error in the result's structured content, with a message, meta and hints. Your agent can act on the error's type without reading the message, and most errors cost nothing.
Tool errors
| Error | Charged | What it means, and what to do |
|---|---|---|
BudgetExceeded | No | The estimate (est_credits) is above your max_credits. Raise the cap or ask for less |
InsufficientCredits | No | The balance is below the estimate. Stop and open upgrade_url: checkout on the free plan, the next plan's one-click confirm on Billing on a paid plan (next_plan names it), Billing alone on the largest plan. On the free plan, resets_at is when the credits come back. In ChatGPT and Codex the link is plans_url instead |
NoData | No | The provider has nothing for this input. Do not retry the same input |
InvalidTarget | No | The input is wrong: a bad domain, a bad parameter or a stale cursor. The message says what to fix. Fix it and retry |
InvalidProvider | No | The provider is not one this tool runs on. Pick one from valid_providers, or leave provider out to use the default |
ProviderUnavailable | No | A provider is down, slow or busy. Retry after retry_after_s |
NotConnected | No | A console or analytics tool needs a Google or Bing account that is not connected, its access was revoked, or the Google grant lacks Analytics. Connect or reconnect it at connect_url and retry |
ConcurrencyLimit | No | Too many of your own calls at once. Retry after retry_after_s, and send fewer in parallel |
TaskPending | No | An async task is still running after get_task waited up to 25 seconds for it. Call get_task again |
TaskFailed | No | An async task failed. The message says why |
TaskPending is not marked as an error, because nothing went wrong. Every other type is.
If an error does not match what happened, or keeps coming back, your agent can report it with submit_feedback. Include the call's request_id so we can find it.
Rate limits
There are two limits, and each workspace has its own:
- Requests. About 120 requests a minute per workspace. Each Cloudflare data centre counts separately, so the limit is approximate. A request over it gets HTTP 429 with
retry-after: 60. - Calls in flight. A set number of calls at a time per provider family, per workspace, by plan: 5 on Free, 10 on Pro and Growth, 20 on Agency. The search tools, the people and company tools, and the social tools are separate families, so that many of each can run at once. Extra calls wait up to 30 seconds for a turn, then return
ConcurrencyLimit.
Sign-in errors
A missing, unknown or expired credential gets HTTP 401 before any tool runs. See Authentication.