Errors and rate limits

One shape for success, one for failure

A success is success: true with the payload under data, and, on the metered data surfaces, a meta block carrying what the call cost and what is left. A failure is success: false with a single error object. There is no third shape, and no endpoint returns a bare payload.

{
  "success": true,
  "data": { },
  "meta": {
    "costCents": 1.5,
    "purchasedBalanceCents": 4821.5,
    "subscriptionRemainingCents": 1000,
    "cached": false,
    "latencyMs": 412
  }
}

error.details appears on validation failures: one entry per offending field, each with field, location (query, path or body) and message. error.retryAfter appears whenever waiting is the right move, and the same number of seconds is sent as a real Retry-After header so an HTTP client can honour it without parsing the body.

Out of money, at a limit, or out of plan

INSUFFICIENT_CREDITS (402) is your balance. The message states exactly what the call required and what was available, so an agent can relay a real number to its human. Nothing happens until someone tops up.

On a builder plan or the trial the plan itself is the budget, so a refusal comes with a way forward. DATA_CREDITS_EXHAUSTED, PLAN_LIMIT_REACHED and PLAN_REQUIRED carry an upgrade offer under error.upgrade: why the call stopped, the next plan and what it costs, and a confirm URL for a person. Over MCP the same offer is the tool result itself, not an error, so the agent relays it instead of burying it.

HTTP/1.1 402 Payment Required

{
  "success": false,
  "error": {
    "code": "DATA_CREDITS_EXHAUSTED",
    "message": "The data credits included in the Starter plan are used up for this billing period; Growth ($149/mo) includes $90 of data credits every month.",
    "upgrade": {
      "status": "requires_upgrade",
      "reason": "included_credits_exhausted",
      "message": "The data credits included in the Starter plan are used up for this billing period; Growth ($149/mo) includes $90 of data credits every month.",
      "current_tier": "builder_starter",
      "upgrade": {
        "tier": "builder_growth",
        "name": "Growth",
        "price_usd_month": 149,
        "included_data_credits_usd": 90,
        "unlocks": { /* every limit Growth raises */ }
      },
      "confirm_url": "https://app.superagnt.com/confirm/<token>",
      "human_step": "The data call did not run and returned no data: this billing period's included data credits are used up. Data calls resume when the plan renews or right after an upgrade. Nothing was charged. Share the confirm_url with a person on this account: they review Growth there and confirm it. You never pay or change the plan yourself. Retry once they have confirmed."
    }
  }
}

UPSTREAM_CREDITS_EXHAUSTED (503) is our account with the upstream provider running dry. It is deliberately not a 402, because a passed-through 402 would read as your problem and send you to a billing page that cannot fix it. The customer-facing message says only that the source is temporarily unavailable; on our side it pages the team.

Every reason an offer can carry is listed on Plans and limits.

What an upstream failure looks like, and what it costs

Curated data sources sit behind upstream providers. Their answers are classified, never passed through raw:

• A valid query that matched nothing is a success: 200 with the source's empty answer, meta.empty set and meta.notice saying so. It is not an error, so do not retry it.
• A source that refuses your input (a value it does not accept, an identifier in the wrong form) becomes VALIDATION_ERROR (400) naming the field.
• A source throttling requests becomes RATE_LIMITED (429) with retryAfter, after we have waited and retried ourselves.
• Upstream server errors, network errors, timeouts and failures reported inside a 200 become PROVIDER_ERROR (503). We retry the ones a retry usually fixes first.
• Our own quota exhaustion becomes UPSTREAM_CREDITS_EXHAUSTED (503), never a 402.
• If your connection closes before the source answers, the call is stopped and not charged.

A retry helper that knows when to stop

Honour Retry-After when it is there, back off on 429, 502 and 503, and never retry a 400 or a 402. A malformed request, an empty wallet and a plan limit do not heal by waiting.

const RETRYABLE = new Set(["RATE_LIMITED", "PROVIDER_UNAVAILABLE"]);

export async function callAgnt(path: string, init: RequestInit = {}) {
  for (let attempt = 0; ; attempt++) {
    const res = await fetch("https://api.superagnt.com" + path, {
      ...init,
      headers: {
        ...init.headers,
        Authorization: `Bearer ${process.env.AGNTDATA_API_KEY}`,
      },
    });

    const body = await res.json();
    if (body.success) return body.data;

    const code = body.error.code;
    const retryable =
      RETRYABLE.has(code) || res.status === 502 || res.status === 503;

    // A 400 is your request and a 402 is your balance or your plan: neither
    // heals by waiting, so stop immediately.
    if (!retryable || attempt >= 4) throw new Error(`${code}: ${body.error.message}`);

    const headerWait = Number(res.headers.get("Retry-After"));
    const waitSeconds = Number.isFinite(headerWait) && headerWait > 0
      ? headerWait
      : body.error.retryAfter ?? 2 ** attempt;

    await new Promise((r) => setTimeout(r, waitSeconds * 1000));
  }
}

Related: workspaces and organizations for where the plan and the wallets live, and the API reference for per-endpoint parameters and pricing.