Ask HN: Standards for API Error Responses?

9 points·BerislavLopac··3 comments

Are there any common guides/standards for returning error messages from network-based APIs (REST, RESTful, RPC...), perhaps some kind of generic schemas? I am aware of RFC-7807 [0], but it seems overly complicated and essentially requires keeping a database of common error types (which admittedly _is_ useful, but usually an overkill). Thanks!

[0] https://datatracker.ietf.org/doc/rfc7807/

View on HN

I have not found a definitive source as yet and depending on the requirements of the task/project/client I have found the following sources excellent guidelines:

* https://stripe.com/docs/api/errors

* https://developers.google.com/search-ads/v2/standard-error-r...

* https://cloud.google.com/blog/products/api-management/restfu...

I love the Stripe API documentation.

When it comes to REST it's important to return correct response code. As to what comes in body is mostly convention and there are no standards. Here is an example for rest: https://github.com/Microsoft/api-guidelines/blob/master/Guid...

JSON-RPC is a bit more concrete: https://www.jsonrpc.org/specification#error_object But again what you put into data is up to you.

Response structure might also depend on the client (content negotiation)

One thing I see people do quite a lot is to write error messages for, or assume error messages are intended for, users of the client application that calls the API.

I feel this is a mistake because in the backend you have absolutely no context about why the call was made, not to mention you aren't going to i18n the errors.

I'd suggest to return an error message designed for the developers using your API, and an error code (as RFC-7807 does) that is machine parsable to identify the type of error, so client applications can react to it and/or display a user friendly error message.

Reply on news.ycombinator.com