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.

Two different ways to be out of money

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.

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.

What an upstream failure looks like, and what it costs

Curated data sources sit behind upstream providers, and their failures are normalized into one code rather than leaked raw:

• A 200 carrying a failure body becomes PROVIDER_ERROR with status 422 — the provider said yes and meant no.
• An upstream 4xx passes its own status through as PROVIDER_ERROR, so a 404 from the source stays a 404.
• Upstream 5xx responses, network errors and timeouts all become 502.
• Our own quota exhaustion becomes UPSTREAM_CREDITS_EXHAUSTED (503), never a 402.

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 and an empty wallet 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: 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.