HTTP Status Codes
Error Response Format
When an error occurs, the API returns a JSON object with a message describing the problem.Some endpoints — notably parameter-validation, rate-limit, and entitlement errors — use an
error field instead of message. Check both fields when handling error responses generically.Detailed Status Code Reference
200 OK
The request succeeded. For list endpoints, the response is a JSON array. For single-resource endpoints, the response is a JSON object.400 Bad Request
The request was rejected because one or more parameters are invalid. Check themessage (or error) field for specifics.
Common causes:
- An invalid
sport_idvalue - A malformed date format (expected
YYYY-MM-DD) - An unrecognized query parameter value
- More than 12
market_idsin a single request
market_ids is omitted, soccer leagues and NHL default to 1,2,3,563 rather than 1,2,3, and market-definition endpoints return all available definitions — see Market IDs.
How to fix: Review the request parameters against the API reference documentation. Ensure all required parameters are present and correctly formatted.
401 Unauthorized
Authentication failed. The API could not verify your identity. Common causes:- No API key was provided
- The API key is invalid or has been revoked
- The
X-TheRundown-Keyheader is missing or malformed
403 Forbidden
Your API key is valid, but the request is blocked by a plan entitlement or an account-level limit. Unlike a401, re-authenticating will not help.
Common causes:
- Requesting a date outside your plan’s history window, which gates events, scores, and odds together
- Requesting live game state or play-by-play (
/api/v2/events/{eventID}/plays) on a tier below Ultra - Requesting futures (
/api/v2/sports/{sportID}/futures) on a tier below Ultra - Subscribing to the multiplexed WebSocket’s
plays,stats, orlivechannel without the live game state entitlement - A hard budget limit configured on the account has been reached
earliest_available_date and history_days_limit from the response. Use a date within that window or retrieve older results with GET /api/v2/events/{eventID}, which is not windowed. Opening-line and closing-line routes still apply an event-date gate. See the history-window response example.
Stats access entitlement errors
For an account subject to the new-account stats policy, a production stats route can return the following additive fields after an evaluation expires or when the account lacks a capability. They identify the missing capability and a safe schema-testing route; they do not make a403 retryable.
feature to show the relevant upgrade context, follow upgrade_url only when the account owner chooses to upgrade, and use sample_url only to test parsing against a fixed complete-game sample. Refresh the authenticated account context before scheduling a new production request. See Stats Access for the policy fields and coverage limits.
On the multiplexed WebSocket, a channel entitlement failure is delivered inside the open connection as {"type":"error","code":"forbidden",...} rather than as another HTTP response.
Statistics metadata temporarily unavailable
If the service cannot resolve the metadata required to classify a production stats request, it returns503 without charging data points:
Retry-After. Billing middleware can omit X-Datapoints, including on errors, so do not depend on that header to identify a non-billable response. Use bounded exponential backoff and preserve any cached result. Do not turn an unknown event or season into an upgrade prompt. A stats 403 is an entitlement result and must not be retried.
If no supported stats policy can be evaluated, the service also returns a non-billable 503 with code stats_policy_unsupported. Treat it as a policy/service condition, not an entitlement denial or an upgrade opportunity.
404 Not Found
The requested resource does not exist. This typically means the event ID, sport ID, or other identifier in the URL path does not match any record. Common causes:- An event ID that does not exist or has been archived
- A URL path that is misspelled or references a deprecated endpoint
429 Too Many Requests
TheRundown uses429 for more than one condition. Read the response body and headers before deciding whether to retry immediately.
- Read
Retry-Afterfirst. - Inspect
X-Datapoints-Used,X-Datapoints-Remaining,X-Datapoints-Reset,X-Tier, andX-Rate-Limit. Free keys also exposeX-Datapoints-Monthly-Used,X-Datapoints-Monthly-Remaining, andX-Datapoints-Monthly-Resetfor their second enforced window. - If the body says
Rate limit exceeded, retry after a short backoff. - If the body says
Daily data point limit reachedorMonthly data point limit reached, this is a usage-window issue, not a one-second throttle. Retrying immediately will not help.
500 Internal Server Error
An unexpected error occurred on the server side. This is not caused by your request.The 0.0001 Sentinel Value
The value
0.0001 appearing in odds or line fields is not an error. It is a sentinel value indicating that a line is currently unavailable or has not yet been posted by the sportsbook.0.0001 rather than null or omitting the field. This ensures a consistent numeric type across all responses and makes it straightforward to filter in your code.
How to Handle 0.0001
Filter out the sentinel value when displaying or processing lines. Treat any field equal to0.0001 as “not available.”
Troubleshooting Checklist
If you are encountering errors, work through this checklist:- Check your API key. Is it present in the request? Is it valid? Try the key against a public endpoint like
/v2/sports. - Inspect the full response. Read the
messagefield in the error response for specific guidance. - Review the request URL. Ensure the path, query parameters, and date formats are correct.
- Check your billing and throttle headers. If you are getting
429responses, inspectRetry-After,X-Datapoints-Remaining,X-Datapoints-Reset, andX-Rate-Limit. - Retry with backoff for 5xx errors. Server errors are usually transient. Retry after a short delay.
- Contact support. If the issue persists, email [email protected] with the request URL, response body, and timestamp.
Retryable vs Non-Retryable Errors
Not all errors should be retried. Retrying a401 won’t fix a bad API key, but a 502 may resolve on the next attempt.
Retry Strategy
For retryable errors, use exponential backoff with jitter to avoid thundering-herd problems when the server recovers. The pattern: waitbase * 2^attempt seconds, add a random jitter, and cap the maximum delay. Three retries is usually sufficient — if the error persists after that, log it and move on.
Complete Error-Handling Wrapper
This wrapper combines retry logic with sentinel value filtering into a single utility you can use across your integration.For strategies to reduce the number of API calls you make (and the errors you encounter), see the Efficient Polling guide and Rate Limits.