CODEWITHSUNDEEP
rest
ThaDon
ThaDon

Reputation: 8068

Conveying a reason with my HTTP Status Code

When building a RESTful service is it standard practice to return a payload (Json) along with an HTTP Status code (say 500, 403)? I find sometimes the status code alone isn't enough context for the calling app.

Upvotes: 2

Views: 106

Answers (4)

Alberto Megía
Alberto Megía

Reputation: 2255

I posted a question about this too here

So at the end I learn what is in the EDIT 2: return your appropiate HTTP status and in the body of the response, a JSON describing the error encountered, like:

HTTP 404
{
  "code": 123,
  "message": "The resource you are looking for does not exists"
}

This is the way Twitter and others works.

Upvotes: 2

Jørn Wildt
Jørn Wildt

Reputation: 4482

The bullet form answer is:

  1. Use the HTTP status codes correct
  2. Use descriptive error messages
  3. Consider localization with respect to other languages
  4. Allow for more than one message
  5. Include additional error codes if the application calls for it
  6. Use letters for status codes
  7. Include links to online resources
  8. Support multiple media types
  9. Include a timestamp or log-reference
  10. Include the HTTP status code
  11. Do not include stack traces

You can find an in-depth answer here: http://soabits.blogspot.dk/2013/05/error-handling-considerations-and-best.html

Upvotes: 0

ioseb
ioseb

Reputation: 16951

Although it is a work in progress, but it worths reading: Problem Details for HTTP APIs

Quote from the specification:

For example, consider a response that indicates that the client's
account doesn't have enough credit. The 403 Forbidden status code
might be deemed most appropriate to use, as it will inform HTTP-
generic software (such as client libraries, caches and proxies) of
the general semantics of the response.

However, that doesn't give the API client enough information about why the request was forbidden, the applicable account balance, or how to correct the problem. If these details are included in the
response body in a machine-readable format, the client can treat it
appropriately; for example, triggering a transfer of more credit into the account.

This specification does this by identifying a specific type of
problem (e.g., "out of credit") with a URI [RFC3986]; HTTP APIs can
do this by nominating new URIs under their control, or by reusing
existing ones.

Upvotes: 2

Jonathan W
Jonathan W

Reputation: 3799

A payload is often returned along with the response code, but usually it explains the response code itself in a generic fashion. For instance, a web server returning a 404 to a client which accepts text/html will likely have 1 HTML page it serves up whenever such a response is necessary. There may be additional contextual information returned (such as the server version, a log identifier for debugging purposes, etc.) but nothing to indicate a more specific reason.

A 400 error series means it's actionable by the client. Adding sub error codes would tightly couple your client to the server.

Upvotes: 0

Related Questions