Errors

curl -i https://api.mentionsapi.com/v1/ask \
  -H "Authorization: Bearer lvk_live_deadbeef" \
  -H "Content-Type: application/json" \
  -d '{}'

X-RateLimit-Limit: 30
X-RateLimit-Remaining: 27
Retry-After: 2

type ApiError = {
  error: { code: string; message: string; details?: unknown };
  request_id?: string;
};

async function callMentionsApi<T>(
  path: string,
  body: unknown,
  attempt = 0,
): Promise<T> {
  const res = await fetch(`https://api.mentionsapi.com${path}`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.MENTIONSAPI_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(body),
  });

  if (res.ok) return (await res.json()) as T;

  const payload = (await res.json().catch(() => null)) as ApiError | null;
  const code = payload?.error?.code ?? "unknown";
  const requestId = payload?.request_id;

  // 429 — always wait the header value before retrying.
  if (res.status === 429 && attempt < 4) {
    const retryAfter = Number(res.headers.get("Retry-After") ?? 1);
    await sleep(retryAfter * 1000);
    return callMentionsApi<T>(path, body, attempt + 1);
  }

  // 500 / 503 — exponential backoff capped at 30s.
  if ((res.status === 500 || res.status === 503) && attempt < 4) {
    const delay = Math.min(2 ** attempt * 500, 30_000);
    await sleep(delay);
    return callMentionsApi<T>(path, body, attempt + 1);
  }

  // 402 — balance is low. Surface to the user, don't retry.
  if (code === "insufficient_credits") {
    throw new Error("Top up at mentionsapi.com/app/billing");
  }

  // 401 / 400 / 404 etc — fix the request, don't retry.
  throw new Error(
    `MentionsAPI ${res.status} ${code}: ${payload?.error?.message ?? "unknown"} (request_id=${requestId})`,
  );
}

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));