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

Status CodeMeaningDescription
200OKThe request was successful. The response body contains the requested data.
400Bad RequestThe request contains invalid parameters or is malformed.
401UnauthorizedAuthentication failed. The API key is missing, invalid, or expired.
404Not FoundThe requested resource does not exist.
429Too Many RequestsYou have exceeded your rate limit. See Rate Limits.
500Internal Server ErrorAn unexpected error occurred on the server.

​
Error Response Format

When an error occurs, the API returns a JSON object with details about what went wrong. 
{
  "error": "short error code",
  "message": "A human-readable description of the problem."
}

​
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. 
{
  "event_id": "abc123",
  "sport_id": 2,
  "teams": { ... },
  "score": { ... }
}

​
400 Bad Request

The request was rejected because one or more parameters are invalid. Check the message field for specifics. Common causes:
  • An invalid sport_id value
  • A malformed date format (expected YYYY-MM-DD)
  • An unrecognized query parameter value
{
  "error": "bad_request",
  "message": "Invalid sport_id: 999. See /v2/sports for valid sport 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 Authorization header is malformed
{
  "error": "unauthorized",
  "message": "Invalid or missing API key."
}
How to fix: Verify that your API key is correct and included in the request. See the Authentication guide for supported methods. 
# Verify your key is being sent correctly
curl -v -H "X-TheRundown-Key: YOUR_API_KEY" \
  "https://api.therundown.io/v2/sports/2/events"

​
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
{
  "error": "not_found",
  "message": "Event not found: abc123"
}
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

You have exceeded the rate limit for your API key. The response includes headers indicating when you can retry. 
{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your rate limit. Please wait before making additional requests."
}
How to fix: Wait until the X-RateLimit-Reset timestamp before retrying. Implement exponential backoff in your client. Consider using delta endpoints or WebSocket to reduce request volume. See Rate Limits for details.

​
500 Internal Server Error

An unexpected error occurred on the server side. This is not caused by your request. 
{
  "error": "internal_server_error",
  "message": "An unexpected error occurred. Please try again later."
}
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. 
{
  "affiliate_id": 1,
  "spread": {
    "point_spread_home": 0.0001,
    "point_spread_away": 0.0001,
    "point_spread_home_money": 0.0001,
    "point_spread_away_money": 0.0001
  }
}

​
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.” 
SENTINEL = 0.0001

def is_line_available(value):
    """Return True if the line value is real, not the sentinel."""
    return value is not None and value != SENTINEL

spread = event["spread"]["point_spread_home"]
if is_line_available(spread):
    print(f"Home spread: {spread}")
else:
    print("Home spread: 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 rate limit headers. If you are getting 429 responses, inspect X-RateLimit-Remaining and X-RateLimit-Reset.
  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.