Skip to content
Tutorials/Performance and operationsIntermediate9 min read

Diagnose API errors and missing football data

Handle authentication, entitlement, validation, rate limits, temporary failures and empty collections with bounded retries and useful diagnostics.

Flow / Diagnose before retrying
  1. Step 1: Status

    Read HTTP and error code

  2. Step 2: Scope

    Check key, plan and inputs

  3. Step 3: Content

    Verify actual records and dates

  4. Step 4: Recovery

    Correct, back off or contact support

Give each failure its own response

For 400 errors, inspect parameter names, date formatting, range limits and required values. Retrying an identical invalid request is not recovery. For 401, check that the REST key is present, active and sent in the documented header.

For 403, check plan entitlement and saved Starter leagues. The global directories, standalone match/profile routes, heatmaps and images require Growth or Pro. A disabled endpoint can instead return 503 with endpoint_unavailable; distinguish that configuration state from a transient source failure. Do not rotate a valid key to fix an excluded plan feature.

  • 400: correct the request.
  • 401: correct authentication.
  • 403: confirm the plan and saved league scope.
  • 429: honour Retry-After.
  • 503 endpoint_unavailable: check endpoint activation rather than retrying indefinitely.
  • Temporary source failures: use bounded recovery and retain the last good snapshot.

Use a bounded retry budget

Temporary rate limiting and source timeouts should not trigger parallel retry storms. Wait for the advertised Retry-After interval where present, add jitter where appropriate, and keep the total attempt count and job duration bounded.

Avoid retrying in several layers at once. If your HTTP client, job runner and browser all independently retry the same work, one failure can become dozens of requests. Have one layer own the retry policy.

Separate empty content from a failed request

A valid empty live feed can mean no matches are in play. A heatmap request without usable coordinates does not establish zero historical coverage. A fresh response can contain old predicted lineups. Inspect the actual record content and dates rather than using HTTP status as a universal coverage indicator.

Keep missing optional fields as missing. If summary, statistics or lineups are empty for a live match, compare the source detail timestamp and exact match ID before assuming your UI rendering is broken.

Collect useful evidence without exposing secrets

Record endpoint name, non-secret query parameters, response status, public error code, request time and relevant fixture IDs. Include the actual dates you expected and received. Do not log Authorization headers, private keys, full credential URLs or unrelated account data.

When contacting support, provide a minimal reproducible request with the credential replaced by an environment-variable reference. Explain whether the problem affects a whole endpoint, one competition or one fixture.

Keep the public page stable during recovery

Continue serving a valid saved snapshot when appropriate, with its real fetched time retained in your system. Do not replace a good archive with an error body or keep a full-page spinner running indefinitely.

After recovery, reconcile the returned state with saved records rather than inserting duplicates. Compare actual IDs and timestamps and only advance your background-job checkpoint after the update is saved successfully.

All 51 tutorials