Error handling and match status values

A 200 means success and a body to parse. A 400 means a parameter is invalid, often a missing required parameter or a wrong format; check the catalogue for the feed's parameters. A 401 means the key is missing or invalid. A 403 means the key is valid but does not have access to that feed, which is common while access is granted per account. A 404 means the feed or resource does not exist. A 429 means a limit was reached. A 5xx means a temporary problem on our side or upstream.

Map each to a distinct exception or error type in your client, so the calling code can decide what to do.

Log the status, the feed, the parameters and the time, but never the key.

Retry network errors, timeouts, 429 and 5xx with exponential backoff, jitter and a cap. Honour Retry-After. Do not retry 400, 401, 403 or 404; they will not change without human action. Alert on those instead.

Keep retries in background jobs. Readers should be served from cache immediately, never kept waiting on a retry loop.

An empty list is not always an error. Before a season starts, standings may be empty. On a day with no matches, today's matches may be empty. But an empty response where yesterday there were twenty teams is suspicious. Compare with the previous stored state, and if the change is implausible, keep the old data and flag it for review rather than overwriting.

Write explicit empty states for each view, so a genuinely empty response produces a clear message rather than a blank space.

Matches have more states than scheduled, in progress and finished. Postponed, cancelled, abandoned, suspended, awarded and delayed are all possible. Store the supplied status string exactly, then map it to a small set of display states in your own code. Log any value you have not mapped yet, and show it neutrally until you do.

Each state needs its own rendering. A postponed match should drop its countdown and show the word postponed. An abandoned match should show the score at abandonment only if supplied, with a clear label. An awarded result should be explained rather than displayed as a normal scoreline.

Some fields are still under confirmation. For example, the time zone of the update stamp on today's matches is not yet confirmed. Treat such fields as internal until our documentation confirms them, and avoid building user-facing features on them.

Readers rarely need technical detail. If data is temporarily unavailable, show the last good copy with its time and a short note. If there is no copy, say the information is not available yet and offer a retry. Never show raw error messages, stack traces or status codes on public pages.

Count errors by status code and feed. A rise in 401 can indicate a revoked or incorrectly deployed key; 403 requires checking account, plan, league and service permissions. A 429 can be a burst or usage restriction, so inspect the error code. For repeated 5xx failures, keep the last-good cache and contact support with the endpoint, UTC time and redacted diagnostic details. Your usage dashboard shows request outcomes.

A Saturday fixture is postponed on Friday evening. The next fixtures refresh stores the new status. The fixture list drops the countdown and shows postponed. The match centre explains that the match has been postponed and will show a new date when one is announced. Standings are unaffected. Weeks later, the same match identifier gains a new date, and every page updates without manual work.

A 400 response usually includes a message naming the problem parameter. Surface that message in your job logs and, during development, in your tooling. The playground builds inputs from each feed's catalogue parameters, including which are required and their formats, so it is a quick way to see a valid request before reproducing it in code.

Dates are a common culprit. Send them in the documented format and the documented zone. Identifiers are another; pass them as strings exactly as supplied, without padding or conversion.

Write tests for every status code your client handles, using a fake server or recorded responses. Test an empty response that should be accepted and one that should be rejected. Test each match status you map, plus an unknown one. These tests are cheap and catch the bugs that otherwise surface on the busiest afternoon of the season.

A request that never returns is worse than one that fails quickly. Set explicit timeouts on every call and treat a timeout like a 5xx: retry later with backoff, keep the cached copy, and log it. Without timeouts, a stalled connection can block a whole refresh run and leave every page stale without any visible error. Track timeout counts alongside status codes in your monitoring.