# Error Codes and Troubleshooting URL: https://sportsgameodds.com/docs/info/errors Error Codes and Troubleshooting [#error-codes-and-troubleshooting] All API errors return an applicable HTTP status code (400-level or 500-level) along with the following JSON body: ```json { "success": false, "error": "Human-readable error description" } ``` TLDR [#tldr] | Code | Meaning | Your Action | | ---- | ------------------- | ------------------------------------------------------ | | 200 | Success | Use the data | | 400 | Bad Request | Fix parameters - check validation errors | | 401 | Unauthorized | Check API key header/parameter | | 403 | Forbidden | Check subscription status or feature access | | 404 | Not Found | Verify endpoint path | | 429 | Rate Limited | Wait and then retry. Upgrade subscriptionif persistent | | 500 | Server Error | Retry once after delay, simplify query if persistent | | 503 | Service Unavailable | Wait for service to reconnect | | 504 | Gateway Timeout | Reduce query complexity, retry once after delay | Types of Errors [#types-of-errors] Non-Standard Response Format [#non-standard-response-format] In rare cases you may receive: * An empty response body * A non-JSON response body (ex: text or html) * A response body which isn't parseable into JSON * A response body without a success field **Meaning:** These are typically due to transient networking issues or server errors. **Recommendation:** * Treat these the same as a 500-level error. * Retry the request once after a short delay * If you see these repeatedly and the request still fails after a retry, please contact support. 400 Bad Request [#400-bad-request] **Meaning:** Your request has invalid or missing parameters. **Troubleshooting**: * Typically the `error` field in the response will be helpful to determine what the issue is * Check the [reference](/v2/reference) docs and the [data-types](/docs/data-types/) docs to help ensure you're using the correct values. * Make sure you haven't included the same parameter multiple times. * If it's a boolean parameter, make sure it's either `true` or `false` (as a string) * If it's a date parameter, make sure it's a valid ISO-formatted date or Unix timestamp. Ex: `2026-01-01T00:00:00.000Z` or `1736899200000` * In some cases, you may be using an invalid combination of parameters. These are combinations of query parameters which can't logically go together such as `live=true` with `ended=true`. 401 Unauthorized [#401-unauthorized] **Meaning:** Authentication failed or API key is missing. **Troubleshooting**: * Make sure you've included your API key either in the header as `x-api-key` (case-insensitive) or as a query parameter as `apiKey`. * Ensure that the API key doesn't contain any leading or trailing whitespace. * Make sure you copied your API key correctly. Check your email and ensure you're using the same key which was sent to you. * Make sure your API key hasn't been re-generated or revoked. 403 Forbidden [#403-forbidden] **Meaning:** Your API key doesn't have permission to access this data **Troubleshooting**: * Make sure you haven't cancelled your subscription. [Check your subscription here](/account). * If you're on a paid plan, make sure you didn't have a failed payment/billing issue * Make sure you're using the latest API version. By default API keys are not granted access to old/legacy API versions. * Certain endpoints may be restricted by tier. For example, the /stream/events endpoint is only available on the AllStar plan. Contact support to upgrade. 404 Not Found [#404-not-found] **Meaning:** The requested resource doesn't exist. **Troubleshooting**: * Make sure you're using the correct URL to query the API. Check for typos. * The version of your API request was invalid. Make sure your URL path starts with `/v2/` or `/v1/` or another valid version. 429 Too Many Requests [#429-too-many-requests] **Meaning:** You've exceeded your rate limits **Troubleshooting**: * Try waiting up to a minute and then try again * Check your rate limit usage using the `/account/usage` endpoint * If you ran out of "objects per month" then you may need to upgrade your plan 500 Internal Server Error [#500-internal-server-error] **Meaning:** Something went wrong on our end. **Troubleshooting**: * Wait a few seconds and then retry the request once. * If it still fails, then contact support * Consider trying a different endpoint or different set of query parameters. Sometimes active problems are isolated to only specific cases of these * In general, these errors are not your fault and should be exceedingly rare * We ask that you do not continuously retry the request as this tends to overload our servers and may result in additional errors 503 Service Unavailable [#503-service-unavailable] **Meaning:** API is temporarily unavailable or our server is offline **Troubleshooting**: * Wait a few seconds and then retry the request once. * If it still fails, then contact support * In some cases, these types of errors are isolated to a single server instance. If that's what's happening, your retry may work. Otherwise, it's likely a more widespread issue with our servers. 504 Gateway Timeout [#504-gateway-timeout] **Meaning:** Request took too long to complete. **Troubleshooting**: * Your query may be too complex. The following can help reduce query complexity: * Remove these parameters: `includeAltLines`, `startsBefore`, `startsAfter`, `playerID`/`playerIDs`, `bookmakerID`/`bookmakerIDs`, `teamID`/`teamIDs` * Reduce the overall number of query parameters you're using * Our servers may be overloaded. Wait a few seconds and then retry the request once. * If it still fails, then contact support Error Handling Example [#error-handling-example]