0

What's the idiomatic way to signal the caller about an error in API, in particular, "Not found" error? Suppose, I have an url /api/vi1/check/123. What should I return in case

  1. There is no such a record with id = 123? 404 error (Http status 404)?

    status: 404 (http); data: { }

  2. Or should I return OK status (Http status 200) and json with the internal status

    status: 200 (http); data: { status: 404, msg: "Not found"}?

  3. And (related to 1) what should I return if there is no such an url? Also Http 404 status?

Yes, I've seen the best practice videos and read the articles about REST APIs but this question wasn't answered clearly in those.

Incerteza
  • 32,326
  • 47
  • 154
  • 261
  • Does this answer your question? [REST API 404: Bad URI, or Missing Resource?](https://stackoverflow.com/questions/9930695/rest-api-404-bad-uri-or-missing-resource) – Michael Freidgeim Jul 31 '21 at 07:18

3 Answers3

2

REST is about using HTTP's semantics. It also applies to error codes. You should use the 404 status code, and eventually a more descriptive error message in the body.

toasted_flakes
  • 2,502
  • 1
  • 23
  • 38
  • And (related to 1) what should I return if there is no such an url? Also Http 404 status? This doesn't seem logical. – Incerteza Aug 10 '14 at 13:01
  • 2
    Following REST principles, a `not found error` and an URL not existing is the *same* thing. An URL is the location of the resource. – toasted_flakes Aug 10 '14 at 13:32
1

Yes you should return a simple 404, no more no less. (Maybe a message to go with that...) That is indicating that the resource you are looking for is not there which is good practice in REST.

martenolofsson
  • 501
  • 1
  • 4
  • 20
-1

It is also good practise not to provide any body here (like an internal status code, or message). If you really need a message in such a case (404 or 500 on an error) you can do that with an additional HTTP header field (e.g. X-Message: Database not available). But a 404 with empty response body is really sufficient here.

Sebastian Daschner
  • 231
  • 1
  • 3
  • and would an user know if the url doesn't exist or the record doesn't exist without the message? – Incerteza Aug 11 '14 at 07:57
  • Like @toasted_flakes said, this is the same thing when thinking in resources. As your services returns JSON encoded data it will be consumed by some client and not accessed by the browser directly (AJAX, Android, JavaFX, etc.). Your client calling the URL should _know_ the base URL (e.g. /tasks/) and notify the user about a not found error (e.g. /tasks/123 got an 404). – Sebastian Daschner Aug 11 '14 at 08:07
  • About the messages: Don't get me wrong it is perfectly fine to add a message, but it should not be returned as the response body. When thinking in resouces you are accessing e.g. a resource task (/tasks/123). So you are expecting the task with ID 123 to be returned in the format you specified in the Accept header field (application/json, application/xml etc). `HTTP 200 OK {"name": "My task", "dueDate": 123456789}` When your application is not able to return it e.g. due to a database error, it should return the status by following [RFC2616](http://tools.ietf.org/html/rfc2616). – Sebastian Daschner Aug 11 '14 at 08:13