HTTP status codes: response category versus application success
By Ai Flowi · Published
HTTP status codes are three-digit response values that describe how an HTTP request was handled. The first digit identifies a broad response category; the specific code supplies more meaning. Application success needs a separate check of the expected body, the intended effect and what information the response exposes.
A caller can receive 200 and still receive the wrong record, an incomplete collection or a private field. Conversely, an error response can accurately describe a rejected request while exposing details that the caller should never see. Treat the code as one piece of evidence in the endpoint’s contract.
Read the response category first
The category helps you decide what to inspect next. It does not replace the meaning of the individual code, the request method or the API’s documented response schema. This is a reading guide rather than an exhaustive status-code registry.
| Class | General meaning | Question for the caller |
|---|---|---|
| 1xx: informational | Interim information about request processing. | Has a final response arrived? |
| 2xx: successful | The request was successfully received, understood and accepted at the HTTP level. | Does this particular response establish the application outcome? |
| 3xx: redirection | Further action is needed to complete the request; this includes cache-related handling. | Is there a redirect or a cached representation to use? |
| 4xx: client error | The request cannot be fulfilled as submitted. | Which request, credential or state condition needs attention? |
| 5xx: server error | The server failed to fulfil an apparently valid request. | What failed, and is the operation’s final effect known? |
An absent response has no observed HTTP status. A connection failure or caller timeout should stay in an “outcome unknown” record, rather than being assigned an invented 500. If a write may already have reached the destination, that uncertainty matters before any repeat attempt.
Distinguish selected API response codes
200 OK indicates successful HTTP handling, but its body meaning depends on the operation. 202 Accepted means processing has been accepted without establishing that it has finished. 204 No Content describes successful handling without response content; demanding a JSON body from that response would be the wrong check.
304 Not Modified concerns a conditional request and use of an existing representation. It is not a new collection payload. A redirect response also needs careful interpretation: the response from the original destination and a later response after following a redirect are different observations.
400 concerns a bad request. 401 concerns authentication; 403 indicates refusal. A 404 does not, by itself, tell you which resource was missing inside a multi-stage application. 429 means too many requests. Server-side examples include 500 for an internal error and 502 for an invalid upstream response. Neither tells you that a previously attempted write had no effect.
What happens when a synthetic 200 response has the wrong body?
Suppose a fictional read endpoint promises exactly two public fields, item_id and state, for the requested item. The request concerns item sample-A. Its contract says that a completed result must identify that same item and use the agreed state value.
{"http_status":200,"content_type":"application/json","body":{"item_id":"sample-B","state":"ready"}}This is an invented observation for interpretation practice, not a recorded endpoint response. The HTTP and content-type checks look acceptable, but the identifier is wrong. The caller must reject the application result rather than show sample-B as evidence about sample-A.
| Synthetic observation | HTTP category | Body verdict | Effect evidence | Disclosure verdict |
|---|---|---|---|---|
| Read returns sample-B for sample-A | 200: successful class | Fails requested-item match | No write required | No extra field in this sketch |
| Write replies “recorded”; destination has no matching record | 200: successful class | Matches the proposed reply shape | Fails complete read-back under the example’s immediate-visibility assumption | No leak shown |
| Job submission returns a job reference | 202: accepted | Matches submission contract | Completion still pending | Check allowed public fields |
| Rejected request includes a private internal reference | 4xx: client-error class | May describe the rejection correctly | Inspect separately if a write was attempted | Fails the public response contract |
For a write, the contract must define how and when a destination read can establish the effect. An incomplete read, a delayed update or a different destination cannot establish that the write is absent. Keep “body correct” and “effect confirmed” as separate conclusions.
What the supplied Sheet JSON API test actually shows
Status: tested. The Sheet as JSON API recipe records 25 of 26 cases passed
on AI Flowi Workflow 1.9.2, tested on 9 October 2026. This was a read-only Google Sheet endpoint, not a general benchmark for API reliability.
Read the recipe’s T20 evidence for the private-identifier disclosure behind its expected 404 response, and webhook error handling for the platform failure boundary. The lesson for interpreting a code is narrower than endpoint approval: a correctly classified refusal still needs a disclosure verdict.
In the synthetic table above, the rejected request therefore needs two findings: whether refusal matched the request contract, and whether the returned fields were permitted. Passing the first finding cannot cancel failure of the second. Record both findings rather than reducing them to a single green indicator for an expected status.
Where status interpretation fits in AI Flowi Workflow
Status: documented. The outbound component contract belongs to the API Request reference; that interface is documented in the catalogue; not production-tested by Ai Flowi
.
When recording an HTTP verdict, identify which response it describes. A gateway refusal, the original endpoint’s redirect and the destination response after that redirect are separate events. If the caller observes a final 200, it should not attach that value to an earlier refusal merely because both events concern the same requested item.
For the sample-A exercise, retain the requested item alongside the observed code and body verdict. If a later response names sample-A correctly, preserve the earlier sample-B mismatch as a failed observation, then assess the later response independently. This keeps an eventual correct result from concealing a faulty response that was already delivered to the caller.
Common interpretation mistakes
- Calling every 2xx response “business complete,” even when a job is only accepted.
- Checking JSON syntax but overlooking the requested identifier, allowed fields or completeness.
- Treating a 404 inside a workflow as proof that its public endpoint address is missing.
- Displaying raw error detail because the status code was expected.
- Repeating an uncertain write merely because its successful reply was never received.
For a runnable response-and-effect check, follow API testing. Related terms: API rate limit for quota interpretation and API pagination for checking whether a collection response is complete.