Sports API Hub connects to external sports APIs hosted on RapidAPI. When API requests fail, the plugin handles errors automatically where possible — retrying, skipping, or stopping gracefully. This page explains each error type, what causes it, and what you can do about it.
Error Code Reference
| Error Code | Meaning | Automatic Handling | What To Do |
|---|---|---|---|
| 401 Unauthorized | Invalid or missing API key | None — request fails | Verify your API key in API & Import > API Config and check your RapidAPI subscription is active |
| 403 Forbidden | Subscription inactive or endpoint not included in plan | None — request fails | Renew or upgrade your RapidAPI subscription |
| 429 Too Many Requests (per-second) | Too many requests in one second | Waits 1 second, retries once | No action needed — handled automatically |
| 429 Too Many Requests (daily limit) | Daily request quota exhausted | Stops the current batch/task | Wait until tomorrow (limits reset at midnight UTC) or upgrade your API plan |
| 204 No Content | No data available for this request | Treated as empty result | Normal response — occurs for finished seasons, future fixtures, or endpoints with no data |
| 500 Internal Server Error | API provider server error | Retries once after delay | Wait a few minutes and retry. This is an issue on the API provider’s side, not the plugin |
| Timeout | Connection to API timed out | Waits 2 seconds, retries once | Check your server’s internet connectivity. If persistent, contact your hosting provider |
The 204 response is not an error — it simply means no data exists for that request. You will see this for finished seasons when requesting next fixtures, or for endpoints that have no data for a particular league.
Rate Limit Handling
The plugin uses a reactive rate-limiting strategy — it does not pre-throttle requests, but handles rate limit errors inline as they occur.
Per-Second Rate Limits
When the API returns a 429 error but the daily quota still has remaining requests, it means too many requests were sent within one second.
What happens: The plugin automatically waits 1 second and retries the request once. If the retry also fails, the individual item is skipped and the batch continues.
You do not need to take any action — this is handled transparently.
Daily Rate Limits
When the API returns a 429 error and the daily quota shows 0 remaining requests, the daily limit has been reached.
What happens: The plugin stops the current import/sync task immediately and returns a “daily limit” error. No further API calls are made until the quota resets.
What to do:
- Wait until the next day — daily limits reset at midnight UTC.
- If you frequently hit the daily limit, consider upgrading to a RapidAPI plan with a higher quota. Daily limits depend on your RapidAPI subscription plan.
- Reduce API usage by disabling import sub-options you do not need (lineups, incidents, highlights) in API & Import > API Config > Import Options.
Checking Your Usage
Visit your RapidAPI Dashboard to see:
- Current daily usage vs. limit
- Historical usage patterns
- Available plan upgrades
🌐 Network and Timeout Errors
Connection Timeout
The plugin uses a 15-second timeout for each API request. If the API does not respond within that window, the request is considered timed out.
What happens: The plugin waits 2 seconds and retries the request once. If the retry also times out, the item is skipped.
Common causes:
- Slow outbound HTTP connections from your server (common on shared hosting)
- Temporary API provider latency or maintenance
- Firewall or security plugin blocking outbound requests
What to do:
- Retry the operation — timeouts are often temporary.
- Check that your hosting provider allows outbound HTTPS connections to
*.p.rapidapi.com. - If timeouts are frequent, contact your hosting provider about outbound connection performance.
SSL/TLS Errors
If you see SSL-related errors, your server’s SSL certificates may be outdated.
What to do: Ask your hosting provider to update the server’s CA certificate bundle.
🔄 Import-Specific Error Behavior
During batch imports (finished games, rosters, teams, etc.), errors are handled per-item:
| Scenario | Behavior |
|---|---|
| Single game fails to fetch | Logged, skipped — import continues to next game |
| Single team fails to fetch | Logged, skipped — import continues to next team |
| Per-second rate limit hit | Auto-retry after 1 second |
| Daily limit reached | Entire import task stops — can be resumed tomorrow |
| API returns unexpected data | Logged, item skipped — import continues |
The import system is designed to be resilient. A failure on one item does not stop processing of the remaining items in the batch — only daily limit exhaustion stops the entire task.
Testing Your API Connection
You can test your API connection directly from the plugin:
- Navigate to API & Import > API Config.
- Enter your API key and select your provider.
- Click the Test Connection button in the sticky bar at the bottom.
The test makes a single lightweight API call to verify your key is valid and the API is reachable. It reports success or the specific error encountered.
Manual Testing with curl
For advanced debugging, you can test the API directly from your server’s command line:
curl -s -o /dev/null -w "%{http_code}" \
-H "x-rapidapi-host: allsportsapi2.p.rapidapi.com" \
-H "x-rapidapi-key: YOUR_API_KEY" \
"https://allsportsapi2.p.rapidapi.com/api/basketball/tournament/all"Replace YOUR_API_KEY with your actual key. A 200 response means the connection is working. Any other code indicates the specific error (see the error code reference table above).
Important: Use x-rapidapi-host and x-rapidapi-key headers (not x-api-host or x-api-key). Using the wrong header names is a common mistake that results in 401 errors.
Checking Import Logs
The plugin tracks import progress for troubleshooting:
- Navigate to Hub Data > Games in the WordPress admin.
- Use the Import Status filter to find games with specific statuses.
- Games that failed during import will show their status in the list table.
Import status values:
| Status | Meaning |
|---|---|
| Fixture | Game scheduled, no details imported yet |
| Detailed | Full game details successfully imported |
| Rechecked | Game re-updated after initial import |
| Skipped | Game skipped during import (e.g., postponed, cancelled) |
When to Contact Support
Contact support if:
- You receive persistent 401 or 403 errors after verifying your API key and subscription.
- Timeouts occur consistently and your hosting provider confirms no connectivity issues.
- Import produces unexpected results even though the API returns valid data.
- You see errors not listed on this page.
When contacting support, include the error code, the operation you were performing (import, sync, live scores), and any console or log output. This helps us diagnose the issue faster.
📚 Related
- API Configuration — API key setup and provider selection
- Common Issues — non-API-related troubleshooting
- FAQ — common questions and answers
- Getting Support — how to contact support