Skip to main content
TheRundown API uses standard HTTP status codes to indicate whether a request succeeded or failed. This page covers every status code you may encounter, the structure of error responses, and how to handle them.

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 the message (or error) field for specifics. Common causes:
  • An invalid sport_id value
  • A malformed date format (expected YYYY-MM-DD)
  • An unrecognized query parameter value
  • More than 12 market_ids in a single request
Requesting more than 12 market IDs returns:
When 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-Key header is missing or malformed
How to fix: Verify that your API key is correct and included in the request. See the Authentication guide for supported methods.

403 Forbidden

Your API key is valid, but its plan does not include the feature you requested. Unlike a 401, 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
How to fix: Upgrade the plan, or remove the gated feature from your integration. The entitlement headers on any metered response show what your key can access.

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
How to fix: Confirm the resource identifier is correct. Use the appropriate list endpoint to discover valid IDs before requesting a specific resource.

429 Too Many Requests

TheRundown uses 429 for more than one condition. Read the response body and headers before deciding whether to retry immediately.
You may also see:
or:
How to fix:
  • Read Retry-After first.
  • Inspect X-Datapoints-Used, X-Datapoints-Remaining, X-Datapoints-Reset, X-Tier, and X-Rate-Limit.
  • If the body says Rate limit exceeded, retry after a short backoff.
  • If the body says Daily data point limit reached or Monthly 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.
How to fix: Retry the request after a brief delay. If the error persists, contact support at [email protected] and include the full request URL and timestamp.

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.
When a sportsbook has not released a line, or when a previously available line has been taken down, the API returns 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 to 0.0001 as “not available.”

Troubleshooting Checklist

If you are encountering errors, work through this checklist:
  1. Check your API key. Is it present in the request? Is it valid? Try the key against a public endpoint like /v2/sports.
  2. Inspect the full response. Read the message field in the error response for specific guidance.
  3. Review the request URL. Ensure the path, query parameters, and date formats are correct.
  4. Check your billing and throttle headers. If you are getting 429 responses, inspect Retry-After, X-Datapoints-Remaining, X-Datapoints-Reset, and X-Rate-Limit.
  5. Retry with backoff for 5xx errors. Server errors are usually transient. Retry after a short delay.
  6. 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 a 401 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: wait base * 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.