Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Reserve the 418 status code

tools.ietf.org

Post reply on HN
Print view View original

101–110 of 124 posts

Re: Reserve the 418 status code

#101

Post by caseysoftware »

eric_b wrote: post #100
caseysoftware wrote: post #94

Earlier quoted context omitted.

No. You should never, ever, ever return a 2xx status code with an error payload. The 2xx series means "Success" and you're abusing HTTP to use it to mean anything else. With regard to application layer vs transport layer, the 404 Not Found, 406 Not Acceptable, 409 Conflict, and many others errors are specifically application layer codes. If you can't get a more specific code, 400 Bad Request with an expressive payloa…

Uh what? If the request was appropriately formatted, not too large, and generally acceptable to the server from a transport perspective, why shouldn't it succeed with a 200? Error handling is an application level concern, not a transport level concern. HTTP status codes lack the nuance required to inform the end user about errors in any non-trivial application. I personally enjoy the OP's solution. I've worked on doz…

Expressive error messages are great. Calling errors a "success" is wrong.

Check out my slides here for more: https://speakerdeck.com/caseysoftware/12-reasons-your-api-su...

Slides 38-40 are specifically about expressive and useful error messages.

Re: Reserve the 418 status code

#102

Post by grandalf »

caseysoftware wrote: post #94
grandalf wrote: post #54

Many API developers misuse/overload HTTP status codes when they should actually be using application specific status codes delivered via a wrapper to the response. Any time an API returns a correct response the HTTP response code should be 2xx. Many developers use 4xx status codes to indicate things like data validation errors or other things that are not part of the HTTP transport. HTTP is the transport layer, and a…

No. You should never, ever, ever return a 2xx status code with an error payload. The 2xx series means "Success" and you're abusing HTTP to use it to mean anything else. With regard to application layer vs transport layer, the 404 Not Found, 406 Not Acceptable, 409 Conflict, and many others errors are specifically application layer codes. If you can't get a more specific code, 400 Bad Request with an expressive payloa…

> You should never, ever, ever return a 2xx status code with an error payload. The 2xx series means "Success" and you're abusing HTTP to use it to mean anything else.

If the transport was successful, then it was an HTTP success.

> 404 Not Found, 406 Not Acceptable, 409 Conflict, and many others errors are specifically application layer codes

These are "application specific" to the resource only, not to the API as a whole. Nor are they particularly informative which is why the spec advocates incorporating a more specific error message. At best, these codes describe a class of errors, possibly useful for logging, but not sufficient for a nontrivial API's error semantics.

My point is not that the HTTP status codes don't mean anything, it's that they are misused to describe application level stuff and used to handle application layer flow control in a way that defeats the purpose and makes them more confusing than they are worth much of the time.

> because we're using the same design patterns consistently and repeatedly.

This is absolutely not the case, every team overloading HTTP status codes seems to do it their own quirky way.

The worst part is when people start bikeshedding about the subtle meaning/intent of HTTP status codes (as your point about 202 illustrates). The simple solution is to define the relevant application layer errors for a specific API and use the HTTP status codes for transport related stuff. It should not matter what 418 or 202 means because the subtle meanings they get int he context of one API/application should not be relevant.

Re: Reserve the 418 status code

#104

Post by grandalf »

caseysoftware wrote: post #101
eric_b wrote: post #100

Earlier quoted context omitted.

Uh what? If the request was appropriately formatted, not too large, and generally acceptable to the server from a transport perspective, why shouldn't it succeed with a 200? Error handling is an application level concern, not a transport level concern. HTTP status codes lack the nuance required to inform the end user about errors in any non-trivial application. I personally enjoy the OP's solution. I've worked on doz…

Expressive error messages are great. Calling errors a "success" is wrong. Check out my slides here for more: https://speakerdeck.com/caseysoftware/12-reasons-your-api-su... Slides 38-40 are specifically about expressive and useful error messages.

Your slides illustrate a custom response payload which happens to use codes that numerically match HTTP status codes. You also use a response message, I think we actually agree. I'd recommend using a different numerical namespace to avoid any possible confusion about the semantics of those codes. Just because they sound the same to one person reading the spec doesn't mean they will make sense to others.

Re: Reserve the 418 status code

#105

Post by caseysoftware »

grandalf wrote: post #104
caseysoftware wrote: post #101

Earlier quoted context omitted.

Expressive error messages are great. Calling errors a "success" is wrong. Check out my slides here for more: https://speakerdeck.com/caseysoftware/12-reasons-your-api-su... Slides 38-40 are specifically about expressive and useful error messages.

Your slides illustrate a custom response payload which happens to use codes that numerically match HTTP status codes. You also use a response message, I think we actually agree. I'd recommend using a different numerical namespace to avoid any possible confusion about the semantics of those codes. Just because they sound the same to one person reading the spec doesn't mean they will make sense to others.

Understood on that point. The response codes are in those payloads purely for illustrative purposes.

Re: Reserve the 418 status code

#106

Post by grandalf »

snuxoll wrote: post #89
grandalf wrote: post #75

Earlier quoted context omitted.

> Don't return a 200 code when the request failed. The request didn't fail, it simply followed application logic and returned a successful response indicating the nature of the application logic to the client. That is not an error condition, it's just application logic.

And said logic determined your input was invalid, HTTP 400 Bad Request is a perfectly reasonable response. If you want to use HTTP as nothing more than a transport layer and return 200 OK's all day then fine, but why are you even using HTTP at that point?

Unless I'm doing some sort of pure REST API I'm simply using HTTP as a transport protocol for my application specific protocol.

If HTTP delivers my application protocol's message successfully, it's an HTTP 2xx, but my application's protocol may have a range of statuses that are not "transport-like" in the way HTTP status codes are, which are the main things that API consumers care about, assuming the basic transport is working.

Re: Reserve the 418 status code

#107

Post by grandalf »

krisdol wrote: post #93
grandalf wrote: post #75

Earlier quoted context omitted.

> Don't return a 200 code when the request failed. The request didn't fail, it simply followed application logic and returned a successful response indicating the nature of the application logic to the client. That is not an error condition, it's just application logic.

So then if my application logic catches a thrown exception because I don't want my app to crash every time a server bug is exposed, I should be returning a 200 OK response rather than a 500 Internal Server Error, because the app logic accounts for handling exceptions and returns a response. I can't disagree more. It just seems like clients would have a nightmare of a time debugging client-side code against such a sys…

If it was an error you expected, then you should handle it using application logic. If you use a programming language with exceptions and one gets thrown and you use it for flow control, that doesn't mean the sever is broken.

The API consumer doesn't need to think there is a problem, since you might have ways of handling it in a more subtle way. Maybe when your DB connection times out you send an application specific message that includes the number of milliseconds to wait for a retry. You don't have to let the shit hit the fan and return a 5xx any time something slightly exceptional occurs, 5xx is for things that are truly exceptional and for which you have no helpful information for the consumer about what to do.

Re: Reserve the 418 status code

#108

Post by grandalf »

dragonwriter wrote: post #97
grandalf wrote: post #54

Many API developers misuse/overload HTTP status codes when they should actually be using application specific status codes delivered via a wrapper to the response. Any time an API returns a correct response the HTTP response code should be 2xx. Many developers use 4xx status codes to indicate things like data validation errors or other things that are not part of the HTTP transport. HTTP is the transport layer, and a…

> HTTP is the transport layer No, HTTP is the application layer. TCP is the transport layer. > and any application specific scenarios are best handled with a custom error namespace that can be returned within any 2xx HTTP response. No, generally application errors should be 4xx or 5xx codes; greater detail can be provided in the payload, sure, but a proper error condition should be returned, 4xx for errors resulting…

> (If you are tunneling another application-layer protocol over HTTP, your argument makes sense, but that's not the general case with APIs.)

I'd argue that that is actually what most APIs are doing that are not purely "REST" operating naively on resources.

As we move up the protocol stack, one is the transport for the next. HTTP is not really the application layer protocol, it's a transport for a protocol defined by the API, at least for any API nontrivial enough to benefit from its own specific error/response codes.

Re: Reserve the 418 status code

#109

Post by grandalf »

nulagrithom wrote: post #92
grandalf wrote: post #74

Earlier quoted context omitted.

> Surely an invalid request is a bad request. Invalid to whom? Should a form submitted with a username that already exists in the system get a 500 response code? What's the server error?

I'd go with 409 Conflict, but I'd also accept 400 Bad Request Incidentally, the RFC for 409 makes it quite clear that this touches the application layer: > Conflicts are most likely to occur in response to a PUT request. For example, if versioning were being used and the representation being PUT included changes to a resource that conflict with those made by an earlier (third-party) request, the origin server might u…

Versioning a resource, per WebDAV is a very specific application.

> using 200 OK for everything that didn't fail at the transport layer is a super frustrating experience regardless of whether or not it's semantically correct

The semantics of my application's protocol do not necessarily mirror the semantics of HTTP, nor are the descriptive statuses semantically similar, since most HTTP statuses are simply about transport (even though a few touch on the "application" of URIs as resources).

Re: Reserve the 418 status code

#110

Post by steveklabnik »

robotmay wrote: post #60
mmmurf wrote: post #55

Earlier quoted context omitted.

> a JSON document confirming no use That would be the better design. No need to overload an HTTP status code meant only to indicate transport status.

Honestly the main reason it works like this is that it was my first foray into Rust, and I found JSON parsing a bit of a pain, whereas matching status codes was very simple. If we expand it to return different options in the future then I'll probably rework it.

Interesting, if you happen to have some time, I'd love to hear about why parsing JSON was a pain.
Post reply on HN