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 its plan does not include the feature you requested. Unlike a401, re-authenticating will not help — this is an entitlement limit.
Common causes:
- Requesting live game state or play-by-play (
/api/v2/events/{eventID}/plays) on a tier below Ultra - A hard budget limit configured on the account has been reached
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. - 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.