Skip to content

TutorialsLesson 14 of 15Operations10 min read

Account, billing, usage, limits and error handling

Understand plans, trials, usage headers and HTTP errors on RacingAPI.net, and build a retry helper that honours Retry-After and never loops on 401 or 403.

  • Read rate-limit headers and usage
  • Classify every error status
  • Retry only what is safe to retry

Plans, trials and billing

Live data requires an active subscription, a confirmed seven-day trial or an administrator approval. The trial starts after the secure on-site checkout, not at sign-up, and renews into the chosen monthly plan unless cancelled before the trial end shown in your dashboard. Manage plans, cards and invoices under Dashboard, Subscriptions. Monthly usage resets on the first day of each calendar month in UTC; changing plans does not reset usage. Current prices and limits are on Pricing.

PlanPer secondPer UTC monthExtras
Developer210,000REST feeds
Professional5100,000REST feeds and widgets for one website
Enterprise10UnlimitedWidgets, MCP, REST tips, live support
Limits per account, across all keys

Extra keys do not add allowance: limits are per account. Successful responses carry X-RateLimit-Limit, X-RateLimit-Monthly-Limit and X-RateLimit-Monthly-Remaining (the monthly headers read unlimited on Enterprise). Dashboard, Usage shows the same picture with request history.

Every error, and what to do

StatusTypical codeAction
401invalid_api_keyMissing, invalid or revoked key. Fix configuration. Do not retry.
403subscription_required / account_suspended / enterprise_requiredNo active plan or trial, suspended account, or a plan gate such as Enterprise-only tips. Do not retry.
404resource_not_foundNot in the selected daily feed. Check the date context.
422invalid_filters / invalid_date / conflicting_date_filters / search_requiredFix the query: valid region and date, page and limit, one day selector, and q for horse search. Endpoint-specific validation codes also exist.
429quota_exceededPer-second or monthly limit. Wait for Retry-After.
503provider_unavailable / endpoint_unavailableRetry transient source failures with bounded backoff. endpoint_unavailable means the feed is not activated: contact support instead of looping.

REST gateway errors include error, code and requestId. Log these and quote the request ID to support; a proxy or network error may not return that JSON shape, so keep the HTTP status too. Authentication, access and basic query-shape checks run before metering. Once metered, an unsuccessful request can still count, including a missing resource, downstream date validation or source failure. Treat request IDs and usage reporting as the evidence, not HTTP success alone.

DiagramRetry decision
Retry decision: step 1, Response arrives; step 2, 401, 403, 422; step 3, 429 or 503; step 4, Give up after N.1 RACINGAPI.NETResponse arrives2 STOP401, 403, 4223 CACHE429 or 5034 YOUR SERVERGive up after N
  1. 1Response arrives. 2xx: use it and cache it.
  2. 2401, 403, 422. Stop. Alert an operator. Retrying cannot help.
  3. 3429 or 503. Wait Retry-After seconds, or exponential backoff with jitter.
  4. 4Give up after N. Serve the last good cached copy and surface the error.
Only 429 and transient 5xx are retried, a bounded number of times.

A bounded retry helper

const NEVER_RETRY = new Set([400, 401, 403, 404, 405, 422]);

export async function racingGet(path, params = {}, attempts = 3) {
  if (!Number.isInteger(attempts) || attempts < 1 || attempts > 5) throw new Error("Use 1–5 attempts");
  const url = new URL(path, "https://racingapi.net");
  url.searchParams.set("region", "uk");
  for (const [k, v] of Object.entries(params)) if (v != null) url.searchParams.set(k, String(v));

  for (let i = 1; ; i++) {
    const res = await fetch(url, {
      headers: { "X-API-Key": process.env.RACINGAPI_KEY },
      signal: AbortSignal.timeout(15000),
    });
    if (res.ok) return res.json();
    const body = await res.json().catch(() => ({}));
    const retryable = res.status === 429 || [500, 502, 503, 504].includes(res.status);
    if (!retryable || NEVER_RETRY.has(res.status) || body.code === "endpoint_unavailable" || i >= attempts) {
      throw Object.assign(new Error(body.code || "http_" + res.status), { status: res.status, requestId: body.requestId });
    }
    const retryAfter = Number(res.headers.get("Retry-After"));
    // A monthly-quota wait can be days: do not sleep a request that long.
    if (retryAfter > 60) throw Object.assign(new Error(body.code || "retry_later"), {
      status: res.status, retryAfter, requestId: body.requestId,
    });
    const wait = retryAfter > 0 ? retryAfter * 1000 : Math.min(30000, 1000 * 2 ** i) + Math.random() * 500;
    await new Promise(r => setTimeout(r, wait));
  }
}

These helpers retry only the listed HTTP statuses, up to the attempt limit. Transport timeouts, connection failures and malformed successful JSON are surfaced to your application, not silently replaced with an empty feed. RacingAPI.net supplies Retry-After in seconds. Waits longer than a minute are returned to the caller so a web request is not held open for hours or days. Use a shared queue to coordinate concurrent jobs as well as retries.

Equivalent helpers live in Code examples. Error codes are listed in the API reference.

Reference material

Exact schemas: API reference. First call: Quickstart. Copy-ready helpers: Code examples. Plans: Pricing.