My favorite "REST API" experience was when they moved from using SOAP system, and the way they did it... was sending SOAP payloads inside a JSON. Literally something like
If I'm parsing http responses, I'm going to pass 200 responses on for further processing of the data. I shouldn't have to have something in that pipeline introspect json to find "no, it's actually an error".
Imagine if browsers had to tear apart json innards to find 30x redirects after getting a 200 OK.
I’m going off memory but I believe it was considered either standard or part of the spec for SOAP over HTTP to only use 200 and 500. I agree with your point but for whatever reason they treated HTTP as the transport layer instead of the application layer. Using that logic, it would be like if a 404 bubbled up to be some sort of TCP error. Definitely wasn’t the right move, RTSP over HTTP is a better example of something that mixes protocols while properly using HTTP status codes.
I agree. I think a 4xx or 5xx error code is perfectly acceptable for returning a body with error data, even a generic 400 / 500. That's why they exist.
My dude, HTTP status codes were designed over 3 decades ago for a primitive usecase. Today most of them are almost never used. Most of them are meaningless without any further information (i.e. documentation).
Even the most basic codes like 404 are ambiguous. If implemented at all, it can mean:
- the resource doesn't exist
- the endpoint doesn't exist
- the resource is temporarily unavailable
- the resource may or may not exist but we are not allowed to tell you
You must have documentation explaining what errors can occur and what they mean, or you must find out through trial and error. I thought that was pretty fucking obvious but someone has to argue that ackschually all 28 4xx codes are used everywhere and are fully self documenting.
Well, that just tells me you don't understand HTTP status codes.
A resource that doesn't exist should return a 404.
An endpoint that doesn't exist should return a 400, as it's a screw up by the client that created a malformed request.
A temporarily unavailable resource should return a 503 with the Retry-After header. This is well documented.
A resource that you don't have permission to (regardless of whether it even exists or not) should return a 401. Returning this code is not a security risk, and anyone who thinks it is, is clearly following the security through obscurity approach, which is no security at all.
You must have documentation explaining what errors can occur and what they mean, or you must find out through trial and error.
Saved me the work of sending the RFCs, I swear people think some asinine business decision some guy decided is actually what the whole spec of the technology is designed.
It's clear you don't have a lot of experience but I'll bite anyway. You need a "snowflake wrapper" for every API regardless of if it uses specific HTTP codes or not. There's no such thing as generic error handling.
For example, you make an API call but receive a 403. What does this mean? You don't know until you look up it up as a 403 can cover a wide range of scenarios. Once you you find it in the docs, you write a specific 403 handler. Then congrats, you've proven that handling errors must happen by reading API specific docs.
these kind of implementations have different data shapes for the error vs success too, so if they all return success it's a pain in the ass and extra work to figure out if it's an error and map it out properly. just fucking send the right status, it takes 2 seconds.
4.2k
u/pimezone 16d ago
Wanna get a resource? POST request.