Reading a mobile API's error taxonomy

Each distinct error names a check that failed

A request passes through a series of checks before it reaches application logic: transport, routing, session state, credential validity, signature verification, freshness, replay protection, payload schema, and account or device binding. Each layer produces its own response, and a single endpoint can return several different errors depending on which layer refused the call. A 401 for an expired token and a 401 for a signature the server could not verify are different failures wearing the same code.

Because the layers are ordered, the first error you receive is information about everything that passed. If the response is a signature error, the session was accepted, the credential resolved to an account, and the request shape was understood well enough to attempt verification. That is a large amount of the flow already excluded, and it narrows the search to the signed material.

The fields that make errors distinguishable

Mobile APIs differ in how much they distinguish, and the distinguishing fields are usually fewer than the error catalogue suggests.

• The HTTP status code. It separates broad classes: authentication, authorisation, validation, conflict, throttling, and server fault.
• An application error code or identifier. Where one exists, it is the most precise signal in the response, because it maps to a single branch in the server's own code.
• A message string. The wording often names the failing value, such as an expired timestamp, a repeated nonce, or an invalid signature.
• A body shape. An empty body, a JSON envelope, an HTML error page, and a plain text line each suggest a different handler, and the handler tells you which layer answered.
• A request identifier. Where the server returns one, it allows a support path and confirms that the request reached application code rather than a proxy.

Two quirks are common enough to check early. Some APIs answer with HTTP 200 and put the real status inside the JSON, so the transport status is not the error at all. Others return the same code for a completely different failure when the request is malformed, so a typo in the path can look like an authentication problem.

Building the map from status and body to cause

Start from one request that works and change one thing per attempt. Each attempt produces a response, and the set of responses becomes a table you can read later. The changes that pay off first are the ones the checks correspond to.

• Remove the authorisation header entirely and record the response.
• Resend with a token that has expired and record the response.
• Corrupt one character in the signature and record the response.
• Move the timestamp outside the accepted window and record the response.
• Reuse a nonce or a request identifier and record the response.
• Change a device identifier, a build field, or an attestation value and record the response.
• Change one field in the body to a value of the wrong type and record the response.

Each recorded pair is a fingerprint of one failing check. The table does not need to be exhaustive to be useful. Six or seven distinct responses usually cover the checks that matter in a reproduction, and the pairs are worth keeping as a file rather than in memory.

Using the map to isolate a fault quickly

With the table in hand, a failure is classified by comparison rather than by speculation. Take the response from the failing call, find the closest match in the table, and read off the layer. Three outcomes cover most of the work.

• A match to a signature response means the request was signed and refused. The work is in the signed material: the order of the fields, the encoding, or the key.
• A match to a session or token response means the request never reached signature checking. The work is in token acquisition and renewal, and changes to the signature will not move the response.
• A match to a freshness or replay response means the signature verified and the request was refused on time. The work is in the clock, the nonce source, or the identifier generation.
• No match at all means the failure is elsewhere. A response outside the table points at transport, routing, or a value the table never varied, which is itself a useful conclusion.

The map also settles arguments about cause. Two people can look at the same 403 and reach opposite conclusions about signing, and a recorded response from a deliberately corrupted signature ends the debate in one request.

Keeping the map current

A taxonomy is a snapshot like any other observation. Providers change response codes, add fields, and occasionally add a check that returns a new error. Recording the date beside each entry makes a stale entry visible when a response no longer matches, and adding the new response keeps the file useful instead of misleading.

There is a boundary worth respecting. A map that records which checks exist is a working document about behaviour you observed. Writing down the values that pass those checks is the part that belongs to an engagement and its authorisation, not to a notes file, because a document that lists working credentials is a liability whether or not anyone acts on it.

Where an API hides its distinctions behind one generic message, the map is thin by design and the work moves to measuring behaviour over time instead. That is a harder investigation, and the honest estimate is that it takes longer, because each hypothesis costs a run against a live endpoint rather than a lookup in a table you already own.

Reviewed 28 September 2026 · SReverse research desk