Why does the frontend still white-screen on empty states when the list API returns an empty array and the detail API returns null?

Bottom line first: When a list API finds no data, return an empty array [] and set total to 0. When looking up details by ID and finding nothing, return null or an explicit error code; do not return an empty object. If a field is not filled in, use null to mean unknown; error scenarios should use error codes. Based on common 2026 delivery practices, once the empty-value shape is fixed, the same API should not sometimes return null and sometimes []. Frontend null-check wrappers and API documentation examples should be done together. White screens and integration rework usually come from empty-value drift, not from frontend skill level.

Why do list returns of [] and detail returns of null still cause frontend null-check mistakes?

Frontend null checks usually first check whether there is data, then decide whether to render an empty state or a list. The problem often arises when the same field is sometimes null and sometimes []: writing data.length will throw on null, while writing if(data) treats [] as truthy, so an empty list may keep showing loading. When multiple clients consume the API, App, mini-program, and Web fallback patterns differ; if the backend shape is not unified, each client tends to add its own logic.

From delivery experience, when there are around 10–30 fields, verbal agreements can hold for a while. Once more than two client platforms call the API and it enters long-term maintenance, rework caused by empty-value drift increases noticeably. The experience range is: 0–2 changes per integration round due to null checks is common; writing empty-value semantics into the contract in advance can usually reduce that to 0–1.

First distinguish four kinds of empty: empty list, empty object, empty field, and empty error

Empty-value discussions get confusing because "list has no data," "object does not exist," "field not filled in," and "request failed" are all called empty. They have different semantics, and their return shapes should not be mixed.

1. Empty list: A collection query returns no results; return [], set total to 0, and consumers render the empty state based on length.
2. Empty object: Looking up details by ID finds nothing; return null or an explicit error code. Returning an empty object is not recommended.
3. Empty field: A field has no value; use null to mean unknown or not filled in. Unless business-equivalent, do not substitute an empty string.
4. Empty error: Timeouts, no permission, and invalid parameters should use error codes and messages. Do not return an empty array that makes the frontend think the query finished.

The reason for this split is that consumer actions differ: empty list renders an empty state, empty object jumps to 404 or shows "not found," empty field shows a placeholder, and empty error requires retry or a message. Mixed together, the frontend can only guess.

How should list, detail, and update APIs each be specified?

Even with no data, different APIs have different concerns. The list API focuses on stable pagination components; the detail API focuses on distinguishing not-found from service exceptions; the update API focuses on avoiding misreading "not passed" as "clear." A common 2026 practice is to define conventions by API semantics rather than changing one global configuration all the way down.

• List API: list returns [], total returns 0; no data on the current page is a normal business result, and the HTTP status can still be 200.
• Detail API: If not found, data can return null with a business error code; 404 is also acceptable, but fix it in the documentation. Do not have half the APIs use 404 and half use null.
• Update API: A field not passed usually means do not update; passing null means clear. This rule must be written into the API documentation, otherwise frontend and backend will clash over what null means.
• Nested lists: If a sub-list inside an object has no data, also return []. This avoids a second null check when data is null and then list is accessed.

Verifiable comparison: practical differences between empty array and null

The comparison below follows common delivery scenarios. It is not a fixed standard, only a way to check trade-offs. Costs are described as experience ranges to avoid arbitrary hard numbers.

• Collection fields return []: The frontend can render directly by length, and loops are safe. The cost is that documentation must state [] does not mean the field is absent, and mocks must cover empty lists.
• Single objects return null: This can express non-existence, but callers must check before accessing properties. The cost is that every client must handle null, and a missed check causes errors.
• Mixing null and []: Saves effort short term, but long term makes each client add its own fallback. The experience range is 1–3 integration rework rounds and 0–2 production empty-state issues being common.
• Unified contract plus frontend null-check wrapper: Costs about half a day to a day upfront; later, each integration round usually saves 0–1 null-check changes, with more obvious gains across multiple clients.

The core of this comparison is not which is better, but letting callers use the same judgment for similar fields. The more callers there are and the longer the API lifecycle, the more obvious the benefits of a unified shape.

Delivery context: practices and costs under constraints

In a project with a tight budget and a short cycle, common constraints are the backend using default serialization configuration, two frontend platforms developing in parallel, and little data in the test environment. If no one unifies empty-value rules, each frontend writes its own fallback; empty list pages occasionally white-screen, and rework often requires a new release. A more stable approach is to do three things first: add three examples to the API documentation for empty list, empty object, and missing field; have the frontend use a unified null-check utility like safeArray; and treat empty data as a normal test case during integration acceptance. The cost is about half a day to a day of upfront alignment; the benefit is usually saving 0–2 rounds of rewrites and explanation costs later. This experience range is not a promise, but a fairly common range in delivery.

Applicable and non-applicable boundaries

Empty-value contracts suit systems with frontend-backend separation, multi-client reuse, externally open APIs, and many lists and pagination. Based on common 2026 delivery practices, as long as there is more than one API caller, or frontend and backend are maintained by different people, it is worth writing "empty list returns [], empty object returns null" into the documentation. The value is reducing null-check forks and making empty states, error states, and no-permission states individually identifiable.

Conversely, internal one-off scripts, single-person small tools, and APIs with fixed fields serving only one page do not necessarily need a dedicated empty-value protocol. In these scenarios, overly detailed rules can cost more in communication than they return. The boundary can be remembered as: Empty-value rules are not better the more there are; rather, the more callers there are and the longer the lifecycle, the more worth fixing they are. An API serving only one consumer that can be changed at any time can first be implemented in the simplest way.

Frequently asked questions

When a list API has no data, should it return [] or null?

Return [] and set total to 0. Then the frontend can render the empty state directly by length, and loops will not error because of null. The key is consistency within the same API.

When a detail API finds no data, should it return null or 404?

Either can work, but fix it in the documentation. When returning null, pair it with a business error code; when returning 404, the frontend handles it as an exception. Avoid having half the APIs use one style.

Why does frontend null checking with if(data) sometimes miss cases?

An empty array is truthy in JavaScript, so if(data) enters the has-data branch, but length is 0; the list may keep showing loading. Null checks should be written separately by type.

If the backend framework serializes empty collections as null by default, should it be changed globally?

First look at the number of callers. For multi-client or externally open APIs, unify the empty-collection shape in serialization configuration and documentation. Internal single-client APIs can stay as they are for now; before changing, validate the impact with empty-data test cases.

Will returning an empty array make the frontend mistakenly think there is data?

Generally no. An empty array has length 0, and the frontend should render the empty state by length. What is truly easy to misjudge is returning an error response as an empty array; error scenarios should use error codes.

If you are currently integrating list or pagination APIs, start with one thing: write one example each for no-data, no-permission, and timeout responses into the documentation, then have the frontend run the empty-data branch according to the examples. The applicable boundary is systems with many callers and APIs that will be maintained long term; temporary scripts or single-client small tools do not need to copy this. Fixing the empty-value shape will save considerable explanation cost for 2026 iterations and legacy API compatibility.