I'm using a client library for an HTTP API. The client exposes objects and methods matching the domain, e.g. Api::Document.download, but the return value is just the http response from the API. As the user I have to parse the JSON response value and check the http response code for errors.

That seems like it's exposing too much implementation, like my code shouldn't have to check document_response.code == 429 to understand that the request was rate limited. I'd rather rescue an Api::TooManyRequestsError. I know that every app which includes the client is going to want to do different things with the errors, but it seems like there are too many options in the http response codes available.

I'm considering putting up a PR to implement this in the library (it is open source), but also wary that other people using this library may be upset if they suddenly get exceptions that they aren't expecting. Since this is a Ruby library, it might be idiomatic to offer a Api::Document.download! method as an alternative that will raise errors instead of expecting that users inspect error codes.

How can I think about this?

1 Answer 1


It's a matter of preference.

--> And you are right that adding exceptions where there were none before is a breaking change.

How about wrapping the library to provide abstraction of responses?

If you don't want to deal with http response statuses in your application code it might make sense to build a wrapper for the library that abstracts away the response statuses and delivers exceptions instead. This breaks no existing code and is optional to use. You could contribute it to the project and see if other people like the idea.

Try sketching out a wrapper...

You might find, while building a wrapper for the library that you are now re-inventing an exception object model to accommodate all useful information from http responses and present any additional information the services may return in addition to the http status.

You might find that this is just a lot of extra work that doesn't help simplify your application code. Or you might find it's just the thing to make life easier and worth the effort.

Often simply sketching this out and looking at a couple of use cases can be enough to make the best path clear.

Why not just use http status instead of inventing a new representation for it?

On the other hand, with an http client library it can be quite practical to expose the http responses, which often carry useful information. Some http statuses are not directly related to the service, but are caused by a proxy or gateway, for example. Why should the library. re-invent that? A library can (should!) also provide a standard representation of additional information for cases where the pure http status is not enough.

My Preference

For what it's worth, I'm happy with an http status plus additional information when appropriate. 200, 201, 204 need no additional information. 400, 500 need additional information to make development and support efficient.

Unless I want to abstract away http entirely and support other protocols, this is fine for me, and preferred over someone's new representation of http status.

If I want to abstract away http, then I must design for that. If the library wants to abstract away http, then it will need to present another layer with appropriately generic handling of response status.

Read Other People's Code

It might be worth looking at how various Ruby http client and rest client libraries approach this. It can be a good way to see the advantages and follies of their approaches to presenting http response status.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.