5

Is it a bad practice when writing a RESTful API to use custom HTTP response codes like:

  • 417 - Password not provided
  • 418 - Database error

API custom response codes

I see there is a list of standard HTTP response codes. However, from looking at Twitter's API, it appears Twitter tries to return standard HTTP response codes when available but their own error codes when they cannot align the error with a standard HTTP response (correct me if I am wrong).

What is the best practice for response codes (especially for errors) while creating a RESTful API? Any comments on the practice which Twitter chose to use?

thecoshman
  • 8,394
  • 8
  • 55
  • 77
Placeholder
  • 4,651
  • 6
  • 33
  • 35
  • 3
    @Vash I would think better of someone with your level of rep. If you are going to fix spelling mistakes, don't just fix one missing letter. – thecoshman Aug 28 '14 at 10:54
  • @thecoshman: http://www.usingenglish.com/reference/irregular-verbs/choose.html - Indeed. I consider myself perfectly fluent in English. Please avoid editing my questions with stuff like "Removed tag, added tag". If you don't have anything creative to say, don't say anything. – Placeholder Aug 28 '14 at 10:59
  • 2
    actually, I was getting more at the fact there are other mistakes that should have been fixed too. Also, keep in mind, this is not *your* question, you just initially wrote it. Changes such as removing 'Rest API: ' from the question title are common practice and appreciated, we have a tag system, use it. – thecoshman Aug 28 '14 at 11:01
  • How come "this is not my question, I just initially wrote it?". Please, I won't even respond to you anymore. P.S: Take time to notice, that I have already used the tag system. :O – Placeholder Aug 28 '14 at 11:04
  • 2
    it's not something against your personally, you just have to keep in mind, this is a community site. So whilst one might think a question is best one way, the community may prefer it presented another. – thecoshman Aug 28 '14 at 12:09
  • @thecoshman, I do not believ that zero fix is bettern than one fix. But this is irrelevant. Have a nice day. – Damian Leszczyński - Vash Aug 28 '14 at 12:14
  • 1
    @Vash-DamianLeszczyński if you are going to fix the question, do it properly. – thecoshman Aug 28 '14 at 12:18
  • 1
    Please can we show some decorum in the forum? I was unable to tell the OP was a non‐native speaker when viewing an early revision of this question, so it can't have been that bad—her English is better than most of the yobs that live near me. Ne pas se laisser entraîner dans ce, Hellen. – Nicholas Shanks Aug 29 '14 at 09:20

2 Answers2

6

Yes, yes it is bad practice... mostly.

One of the tenets of REST is that you work with the underlying protocols, as such HTTP has already defined a good set of response codes.

However, not every situation is catered for perfectly. Take Twitters 'arrest your calm', that response code is used when the request was valid, it simply is not being handled due to too many request being made.

I don't see another response code that quite matches that. The other two options are to either lie, and tell the user the request failed for some other response or give a generic 400 'you did something bad' (then in the body give a more detailed explanation).

I would favour using the generic X00 codes, and use headers or the body to add more detail about what actually went wrong. This at least conforms better to standards and less brittle.

Note though, it is terrible to take an existing error code, and repurpose it. 404 should always be used only for 'not found' errors. Don't start using it because the user can't make that request at this time of day.

thecoshman
  • 8,394
  • 8
  • 55
  • 77
  • 1
    Given your example of Twitter's 420 'Enhance your calm', technically that could be a [202](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.2.3) _"The 202 response is intentionally non-committal."_, maybe a [413](http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html#sec10.4.14) with a `Retry-After` – Mark Rotteveel Aug 28 '14 at 19:55
  • 2
    429 Too Many Requests – Cerad Aug 28 '14 at 22:24
  • @Mark no, 202 implies the request *might* be processed at some stage, where as really the response needs to say "it's *never* going to happen". And 413 is for "request too large", which is different from "too many request". – thecoshman Aug 29 '14 at 07:43
  • @Cerad yes, 429 seems like the perfect response code for what Twitter need. Not sure what came first though, if 429 was already 'standardised' with the RFC then it should have been used clearly, but I think Twitter was using 420 before then. I'm not even sure if they still are using 420. – thecoshman Aug 29 '14 at 07:45
  • @thecoshman 413 says _"the request entity is larger than the server is **willing** or able to process"_, it doesn't specify reasons (which might well be too many requests), but the `Retry-after` indicates a back-off which might be an effective way to rate limit. However 429 seems to be a better choice (and it also defines `Retry-after`). – Mark Rotteveel Aug 29 '14 at 07:50
  • 1
    @Mark 413 is about the **size** of the request. It would not be semantic to use that error code for anything other than the size of the request. – thecoshman Aug 29 '14 at 07:54
  • And just for info, Twitter has depreciated 420 in favor of 429. https://dev.twitter.com/docs/error-codes-responses – Cerad Aug 29 '14 at 13:01
6

The problems in using your own codes are:

  1. The code you choose may get officially assigned to something completely different, and that could break your API in the future. (e.g. compare a 306 with a 301)
  2. Intermediaries don't know what your code means, so cannot optimise anything. The internet works so well because it is a distributed system, not an end-to-end system.
  3. There are generic responses for each category, x00, which should be used if nothing better exists.
  4. You can send your own more specific error code in either the response body or (not as good) a response header. There should be no need to make up your own codes. If you have truly found something that would benefit the rest of the internet and no-one else has thought of until now, you can always submit an Internet Draft to the IETF (this is fairly easy to do).

I would not hold up Twitter as a shining example of good internet practice, though. :)

Nicholas Shanks
  • 10,623
  • 4
  • 56
  • 80