# API Error Codes

This page lists API error codes and their common causes. If you encounter an error that is not documented on this page, it can be reported to team@the-odds-api.com. Be sure to include the full API URL that caused the error.

Errors can depend on the specific endpoint being called. For details on specific endpoints and example API requests, see the docs.

# MISSING_KEY

An apiKey query parameter is required for all calls to the API, for example

https://api.the-odds-api.com/v4/sports?apiKey=YOUR_API_KEY

# INVALID_KEY

The API key was invalid or not associated with a subscription.

For sample URLs, the API key is commonly YOUR_API_KEY or {apiKey}, in which case it will need to be replaced with a valid API key associated with a subscription.

# DEACTIVATED_KEY

The API key has been deactivated, most commonly due to subscription cancelation. To regain access to the API, a new subscription is required.

# EXCEEDED_FREQ_LIMIT

The request was rate-limited (HTTP status code 429). Reduce the number of API calls being sent concurrently by spacing out API calls over several seconds. The rate limit is currently 30 API calls per second.

There are a couple of reasons that 429's can occur:

If our system receives a large increase in traffic, it will take some time to scale up, usually in the order of minutes. Whilst this is happening, some requests might be knocked back with 429s.
If requests are sent at a rate close to the limit, some requests can still trigger rate limiting since our servers can receive requests at a different rate to which they are sent. For example, if you send 30 requests per second for 2 seconds, our servers might receive 25 requests in the first second, 33 in the next second (3 of which will be limited), and the remaining 2 requests after that. The rate at which our systems receive the requests will depend on network conditions, which are influenced by many factors outside of our control.

Both of these scenarios mean that 429s can occur sometimes, and they are more likely if requests are being sent close to the limit.

To handle a request that has been rate limited, consider retrying the request after a couple of seconds. Also avoid unnecessary API calls. For example, API calls to the sports or events endpoints can be made infrequently, since the responses don't change often.

# OUT_OF_USAGE_CREDITS

The usage credit limit of the subscription has been reached for the month.

Usage credits can be monitored by accessing the HTTP response headers, which are returned with every API call:

x-requests-remaining The usage credits remaining until the quota resets
x-requests-used The usage credits used since the last quota reset
x-requests-last The usage cost of the last API call

Usage can be tracked and subscriptions can be changed in the accounts portal. If you have not already done so, you will need to create a new account, even if you have active subscriptions. A new account can be created here.

# Troubleshooting Unexpected Usage

If usage is higher than expected, these tips might help identify the cause:

Be sure to familiarize yourself with usage quota costs of API calls. This will depend on the endpoint being called. Details and examples can be found in the "Usage Quota Costs" section of relevant endpoints in the docs.
Consider if you have any automated scripts running which may have been forgotten.
Your API key may have fallen into the hands of an unauthorized user. This can happen if the API key was committed to a public repository, or if it was used on the frontend of a public facing website. An API key can be regenerated in the accounts portal.

# MISSING_REGION

The endpoint being called requires a regions query parameter, which specifies regions of bookmakers to be queried, for example &regions=us,uk

Alternatively the bookmakers parameter can be used, for example &bookmakers=draftkings,pinnacle

A list of valid bookmakers and regions can be found here.

# INVALID_REGION

One or more of the specified regions is invalid. A list of valid bookmaker regions can be found here.

Multiple comma-separated regions can be specified, for example

https://api.the-odds-api.com/v4/sports/soccer_epl/odds?apiKey=YOUR_API_KEY&markets=h2h&regions=uk,eu

# INVALID_BOOKMAKERS

The bookmakers parameter can be used as an alternative to the regions parameter. The bookmakers parameter is a comma-separated list of one or more bookmaker keys. A list of bookmaker keys can be found here.

Multiple comma-separated bookmaker keys can be specified. Bookmakers can be from any region, for example

https://api.the-odds-api.com/v4/sports/basketball_nba/odds?apiKey=YOUR_API_KEY&markets=h2h&bookmakers=draftkings,fanduel,pinnacle

# MISSING_MARKET

The endpoint being called requires a markets query parameter, which specifies betting markets to be queried. For most endpoints, this parameter is not required and will default to the h2h market.

# INVALID_MARKET

One or more of the markets being queried are invalid or unsupported by the endpoint being used. A list of valid market keys can be found here.

This error is commonly caused when non-featured markets are used with the odds or historical odds endpoints, which only support featured markets.

Non-featured markets, such as player props, period markets and alternate markets can be queried one event at a time using the event-odds or historical-event-odds endpoints.

For example, this will cause an error since player_points is a non-featured market, and the odds endpoint only accepts featured markets:

https://api.the-odds-api.com/v4/sports/basketball_nba/odds?apiKey=YOUR_API_KEY&regions=us&oddsFormat=american&markets=player_points

The events-odds endpoint accepts any markets. In this example, b308ed60cbb2d1324946c7289190cc88 was the event id of the Timberwolves @ Nuggets game on 2024-05-04. The event id will need to be replaced with a current event id, which can be obtained from the events endpoint.

https://api.the-odds-api.com/v4/sports/basketball_nba/events/b308ed60cbb2d1324946c7289190cc88/odds?apiKey=YOUR_API_KEY&regions=us&oddsFormat=american&markets=player_points

# INVALID_MARKET_COMBO

This error usually occurs if the sportKey represents an outrights (futures) event, in which case the valid market is outrights.

For example this will cause the error:

https://api.the-odds-api.com/v4/sports/americanfootball_nfl_super_bowl_winner/odds?apiKey=YOUR_API_KEY&regions=us&oddsFormat=american&markets=h2h

This is a valid combination

https://api.the-odds-api.com/v4/sports/americanfootball_nfl_super_bowl_winner/odds?apiKey=YOUR_API_KEY&regions=us&oddsFormat=american&markets=outrights

# INVALID_DATE_FORMAT

The specified dateFormat query parameter is invalid. For valid formats, see the "parameters" section for the relevant endpoint in the docs.

The dateFormat parameter is not required for most endpoints, and will default to iso (ISO8601).

# INVALID_ODDS_FORMAT

The specified oddsFormat query parameter is invalid. For valid formats, see the "parameters" section for the relevant endpoint in the docs.

If this parameter is missing, the oddsFormat will default to decimal.

# INVALID_ALL_SPORTS_PARAM

The all query parameter must be true or false.

This will likely be relevant for the sports endpoint.

# INVALID_SPORT

The sport path parameter is missing or invalid. A list of valid sport keys can be found here, or by called the sports endpoint.

# UNKNOWN_SPORT

The specified sport is not found. A list of valid sport keys can be found here, or by called the sports endpoint.

# INVALID_SCORES_DAYS_FROM

The daysFrom parameter must be an integer greater than or equal to 1, and less the maximum specified in the docs (see the "parameters" section of the relevant endpoint).

For example

https://api.the-odds-api.com/v4/sports/baseball_mlb/scores?apiKey=YOUR_API_KEY&daysFrom=2

# INVALID_EVENT_IDS

The eventIds query parameter is invalid. For endpoints that return a list of events, this parameter is used to filter the API response to specific events. This parameter must contain comma separated event ids, each of which is 32 characters in length.

Depending on the endpoint being queried, event ids can be found by calling the events endpoint or the historical events endpoint.

# INVALID_EVENT_ID

The event id parameter in the URL path is invalid. The event id must be 32 characters in length.

Depending on the endpoint being queried, event ids can be found by calling the events endpoint or the historical events endpoint.

For example, c163b5f5f4579c8293266956ccf3d9bd is the event id for Tampa Bay Rays @ Los Angeles Angels on 2024-04-09:

https://api.the-odds-api.com/v4/historical/sports/baseball_mlb/events/c163b5f5f4579c8293266956ccf3d9bd/odds?apiKey=YOUR_API_KEY&markets=totals_1st_5_innings&regions=us&oddsFormat=american&date=2024-04-08T15:10:00Z

# EVENT_NOT_FOUND

The event id specified in the URL path was not found. The most common cause is that the event has concluded. This error can also occur if the event id was not correctly specified.

# MISSING_HISTORICAL_TIMESTAMP

The date parameter is required when querying historical endpoints. This represents the timestamp of the historical snapshot to be queried. More information can be found for the relevant endpoint in the docs.

# INVALID_HISTORICAL_TIMESTAMP

The date parameter must be in ISO8601 format, for example:

https://api.the-odds-api.com/v4/historical/sports/baseball_mlb/odds?apiKey=YOUR_API_KEY&regions=us&markets=h2h,spreads&date=2024-04-30T12:45:00Z

# INVALID_COMMENCE_TIME_FROM

The commenceTimeFrom parameter must be in ISO8601 format, for example 2024-04-30T00:00:00Z

# INVALID_COMMENCE_TIME_TO

The commenceTimeTo parameter must be in ISO8601 format, for example 2024-04-30T23:59:59Z

# INVALID_COMMENCE_TIME_RANGE

The commenceTimeTo parameter must be later than commenceTimeFrom

# HISTORICAL_UNAVAILABLE_ON_FREE_USAGE_PLAN

Historical data is only accessible on paid usage plans.

Sample historical data can be found here.

# INVALID_PARTICIPANT_ID

The participant id is invalid. It must start with par_, for example par_01hqmkq6fceknv7cwebesgrx03

# INVALID_INCLUDE_LINKS

The includeLinks parameter determines whether links to bookmaker websites will be included in the API response.

If includeLinks is provided, it must be either true or false.

If includeLinks is not provided, it will default to false.

# INVALID_INCLUDE_SIDS

The includeSids parameter determines whether source ids (sids) will be included in the API response. An example of a sid includes a bookmaker's id for an event, market or betting selection.

If includeSids is provided, it must be either true or false.

If includeSids is not provided, it will default to false.

# INVALID_INCLUDE_BET_LIMITS

The includeBetLimits parameter determines whether a bookmaker's bet limits will be returned in each betting outcome in the API response.

If includeBetLimits is provided, it must be either true or false.

If includeBetLimits is not provided, it will default to false.