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.
| Plan | Per second | Per UTC month | Extras |
|---|---|---|---|
| Developer | 2 | 10,000 | REST feeds |
| Professional | 5 | 100,000 | REST feeds and widgets for one website |
| Enterprise | 10 | Unlimited | Widgets, MCP, REST tips, live support |
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
| Status | Typical code | Action |
|---|---|---|
| 401 | invalid_api_key | Missing, invalid or revoked key. Fix configuration. Do not retry. |
| 403 | subscription_required / account_suspended / enterprise_required | No active plan or trial, suspended account, or a plan gate such as Enterprise-only tips. Do not retry. |
| 404 | resource_not_found | Not in the selected daily feed. Check the date context. |
| 422 | invalid_filters / invalid_date / conflicting_date_filters / search_required | Fix the query: valid region and date, page and limit, one day selector, and q for horse search. Endpoint-specific validation codes also exist. |
| 429 | quota_exceeded | Per-second or monthly limit. Wait for Retry-After. |
| 503 | provider_unavailable / endpoint_unavailable | Retry 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.
- 1Response arrives. 2xx: use it and cache it.
- 2401, 403, 422. Stop. Alert an operator. Retrying cannot help.
- 3429 or 503. Wait Retry-After seconds, or exponential backoff with jitter.
- 4Give up after N. Serve the last good cached copy and surface the error.
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.