Design error message for HTTP APIs using RFC 7807

 

In this post, I am going to talk about the RFC 7807, which documents the standard http error message structure.

 

If you are working with webservices, then you might have seen http error codes like below.

a.   400 (Bad Request)

b.   401 (Unauthorized)

c.    403 (Forbidden)

d.   404 (Not found)

e.   500 (Internal Server error)

f.     503 (Service unavailable)

g.   504 (Gateway timeout) etc.,

 

But sometimes, these http status codes alone not sufficient to convey the details about the error. To address this problem, we need a standardized error structure, that can be uniformly accepted by the applications and provide meaningful insights about the error. Here RFC 7807 comes into picture.

 

As per RFC 7807, error or problem details object has the following members.

 

Member	Data type	description
type	String	URI references that identifies the problem type.
title	String	A short, human-readable summary of the problem type. ‘title’ help the users who are not aware of semantics of URI and do not have the ability to discover them
status	number	Http Status code
detail	String	A human-readable explanation specific to this occurrence of the problem.
instance	String	A URI reference that identifies the specific occurrence of the problem.  It may or may not yield further information if dereferenced.

 

Example 

{
  "type": "https://demo.com/probs/insuffecient-funds",
  "title": "You do not have enough funds in the linked accounts.",
  "detail": "Your current balance is 2500, but that costs 7500.",
  "instance": "https://demo.net/account/12345/msgs/abc",
  "status" : 403
}

 

Apart from the standard members, you can add additional members to the error object to convey more details.

{
  "type": "https://demo.com/probs/insuffecient-funds",
  "title": "You do not have enough funds in the linked accounts.",
  "detail": "Your current balance is 2500, but that costs 7500.",
  "instance": "https://demo.net/account/12345/msgs/abc",
  "status" : 403
  "balance": 7500,
  "linked_accounts": [
    "https://example.net/account/12345",
    "https://example.net/account/67890"
  ]
}

 

Note

a.   Both "type" and "instance" accept relative URIs; this means that they must be resolved relative to the document's base URI

 

References

https://www.rfc-editor.org/rfc/rfc7807

 

 

Previous                                                 Next                                                 Home