Distinguishing Empty API Results from Failures

Resumen

Pixel shares a backend case study on an API that used HTTP 200 and status 0 for both empty results and genuine failures. The approach preserves the existing mobile contract while classifying responses as normal, refusal, or fault and adding stable machine-readable codes at a single response hook.

DEV Community

HTTP 200, status 0, nothing wrong: teaching an API to tell empty from broken

I'm Eric Gitangu. I work on the backend of a mobility/fintech platform. This is one problem from the last two weeks: an API that answered "nothing nearby" and "the store is down" with the same shape, and how I taught it the difference without breaking a single installed app. The problem The mobile API wraps every answer in an envelope. The HTTP status is 200 and a status field inside says whether it worked: 1 is success, 0 is failure. That contract is older than most of the code around it, and the apps in people's pockets depend on it. A monitor watches for silent failures: 200 on the wire, status 0 in the body. When I read a few days of its log, a lot of what it had caught was not failure at all. A driver with no rides nearby. An empty queue. An empty document list. A setting nobody had configured yet. Each one answered status 0, because at some point "no results" was written down the error path. Three things follow from that: The app can't tell "nothing here" from "something broke". Both arrive as failure. The monitor counts ordinary days as failures. An alert that pages on a normal state teaches people to ignore the alert. A real fault hides in that noise. Same shape, same count. The decision The textbook fix is real HTTP status codes. Not available: installed builds read the envelope, and I can't recall an app from someone's phone. So the rules were: No existing key, header or status changes for a client that did not ask for it. Status 0 splits into three classes: normal state (nothing to show), refusal (you may not, and here is why) and fault (we broke). Every status-0 answer carries a stable, machine-readable code. Classification happens in one place, not at every call site. One choke point A hook sits at the last point before the response leaves. If the answer is JSON with status 0 and no code, it looks the message up in a catalog and adds a code and a reason. It only adds. It also publishes the code in a response header, so the access log and the monitor see it without parsing bodies. CATALOG = {
"No rides available": ("no_results", "normal"),
"Account not verified": ("unverified", "refusal"),
"Could not read store": ("store_fault", "fault"),
}

def classify(request, body):
if not is_app_request(request) or body.get("status") != 0:
return body, None
field = "error_code" if request.route in ECHOES_ONE_TIME_CODE else "code"
if field not in body:
code, _ = CATALOG.get(body.get("message"), ("unclassified", "unknown"))
body = {body, field: code} # add only: no key removed or changed
code = body[field]
return body, code if code in STABLE_CODES else None # header gets stable codes only
A complete, runnable version with the baseline test is in this gist. The monitor then counts only what is unclassified or uncoded. Everything else is a known answer with a name. To stop the pile growing back, a test walks the source for status-0 sites and compares them with a committed baseline. A new site with no code and no catalog entry fails the build. The debt can shrink. It cannot grow. Three things that bit The hook was too greedy. Payment providers call routes on the same API, and a provider's callback body is the provider's contract, not mine. The classifier now applies only to requests that carry the app's session token header, and provider routes are excluded by name. That fix went in the same day as the hook. code was already taken. Several endpoints return a one-time code in a field called code, and installed builds read it as exactly that. Put a refusal code there and an installed build reads it as the one-time code. On those routes the refusal goes in error_code, and the header copies only values from the stable list, so nothing that isn't a stable code reaches the access log through it. The version gate could never open. The plan was to answer normal states with status 1 only for app builds at or above a minimum version, so older builds kept today's behaviour...
Distinguishing Empty API Results from Failures
Powered by Readybot.io

Lo último de Pixel

Incident Response: Look Beyond the Red Alert

Pixel’s DEV Community announcement explores how teams can fixate on one failing service while overlooking the real cause of an outage, such as a full …

Sach: AI Fact-Checks WhatsApp Forwards in India

Pixel’s announcement introduces Sach, a tool that checks forwarded messages in English, Hindi, Telugu, and 14 other Indian languages against official sources. It gives cited …

Java 25 Removes SecurityManager: What to Fix

Pixel’s announcement explains how Java 24’s JEP 486 permanently disabled the SecurityManager, breaking test workarounds that intercept System.exit. It recommends returning exit codes or throwing …