Why an empty array is a bad answer in OpenFoot API

Empty arrays hide missing data

An empty array in a JSON payload conveys "no items" but provides no context. For a sports data API, that could mean the competition truly has no matches in the queried window, or it could mean the API chose not to serve data for that competition.

Because the OpenFoot API covers 75 competitions, some may be excluded from a particular request due to plan limits, licensing, or other policy reasons. Returning an empty array without explanation forces the client to guess, which can lead to silent data gaps in downstream applications.

How OpenFoot signals an unavailable competition

When a competition is searched but deliberately not served, OpenFoot includes a `meta.unavailable` object in the response. The object lists the competition identifier and a `reason` field that explains why the data is omitted.

The presence of `meta.unavailable` is separate from the HTTP status code; the request still succeeds with a 200 status, but the payload tells the client that the competition was intentionally left out.

Distinguishing unavailable data from real errors

Real errors are reflected in the HTTP status line. For example, exceeding the free Starter quota yields HTTP 429, and attempting to use a feature not covered by the current plan returns HTTP 403 with the code `plan_upgrade_required` and a feature name.

In contrast, an empty array accompanied by a `meta.unavailable` entry is not an error—it is a business‑level decision. Clients should treat it as a signal to skip that competition rather than to retry or abort.

Client‑side handling strategy

First, inspect the response metadata. If `meta.unavailable` is present, log the competition identifier and the supplied reason, then continue processing any other data that was returned.

If the response contains an empty array **without** a `meta.unavailable` entry, interpret it as a genuine lack of matches for the requested window. This situation is common for the default `/v1/matches` query, which only covers today ± three days as described in `meta.scope.window`.

Testing and monitoring

Implement automated tests that simulate both scenarios: an empty array with `meta.unavailable` and an empty array without it. Verify that your client distinguishes the two paths and that it respects quota limits, handling HTTP 429 by backing off until the quota resets on the 1st of the month (UTC).

Monitoring should also capture any 403 responses with `plan_upgrade_required`. Those indicate that the client is requesting a feature—such as lineups, live events, or Expected Goals—that is not part of the current subscription and will need a plan change.

Frequently asked questions

What does an empty array mean in an OpenFoot response?

It can mean either that there are no items for the requested filter, or that the API deliberately omitted a competition. The difference is clarified by the presence or absence of a `meta.unavailable` entry.

How can I tell if a competition was deliberately omitted?

Check the top‑level `meta.unavailable` array. If the competition identifier appears there, the API has supplied a reason for the omission.

Should I retry when I see `meta.unavailable`?

No. `meta.unavailable` is not an error condition; it signals a business decision. Retrying will return the same result. Instead, handle the omission gracefully and consider whether a higher‑tier plan is required.

Sources and further reading

Product descriptions and examples were checked against the OpenFootAPI v1 contract on 1 September 2026.