Testing REST endpoints with fake HTTP statuses

Sometimes when developing a service that calls an external REST API or testing calling an endpoint from a front-end, you'll need to test what happens when that API returns different HTTP status codes. You can do this using tests, and mock/stub a 404, 500, etc. But often it's very helpful to see what happens when a specific response status is returned.

Or imagine your QA team needs to manually test what happens when a 500 is returned. For example, they need to confirm an error page shows if the app receives an error response. In that scenario you can't (purely) rely on stubbed automated tests.

Anytime you have to stub responses, that setup can be tricky and can slow you down. You could go an alternative route and setup your own server that returns 404, 401, 500, etc. And then you could manually swap out the endpoints that get called to point to your "stubbed" service, or using some complicated proxy setup to forward the requests. But that also takes time, adds complexity, and will slow you down.

Rather than having to spin up your own server or only handle this via tests, you can use free 3rd party services that do this for you! This will make seeing how your code handles different HTTP response statuses, with scenarios like the below much easier:

  • Node (or any language) REST API -> external endpoint
  • UI/Front-end -> REST API

Using a 3rd party service

One of the best tools I've found for testing out different responses from a service is httpstat.us.

This service will let you call pretty much any standard HTTP response status as an endpoint, and get that response code returned. For example, calling https://httpstat.us/503 (with GET/POST/etc) will return a 503 Service Unavailable response.

I've used this for testing that a generic "hit an error" page/component gets triggered when the app hits any 500-level errors in an HTTP interceptor. This is an especially good use case for QA teams, because if they are testing this scenario, and you don't want to bring down your server in a dev/UAT environment they can just swap out your server endpoint for something like https://httpstat.us/500 and test that way (ideally the URL is already defined as an environment variable to avoid a code change).

You can also simulate slowness/latency by adding a sleep query param like https://httpstat.us/503?sleep=5000. This is very useful for testing how the UI behaves when having to wait for a slow endpoint. For example, you test using this delay and realize that one component is blocking loading of data for several other components until the first (slow endpoint) response is received.

Lastly, I also use this when I'm working on a frontend feature and the backend endpoint isn't ready yet, and I don't need a response body, just the status.

For POST/PATCH/PUT requests you can send data in the request body, but it will just be ignored. Be careful with this, because although they claim they don't log any data it's hard to verify that and know for sure. So just don't send any sensitive customer data or anything like that.

Using this service on the backend

I went over two use cases on the frontend above, now will go over a use case for using https://httpstat.us/ on the backend.

Often your backend service will need to communicate with external third party services via REST, and this is where this mocked service can come in handy. Because while you will likely have some integration or end-to-end tests for your backend service that test how it handles receiving different HTTP responses, you will also likely want to "smoke" test this manually.

So if I'm calling the Google Maps API as part of my backend service, I could swap the URL out for https://httpstat.us/ with whatever HTTP response code I want to test and confirm my code behaves as expected, does error handling properly, etc.

Similarly, let's say there is another team within the company that is working on an endpoint that is not quite ready yet, but all I need is a 200 or 201 response code and not the resposne body. Instead of holding up my development work waiting for them, I can swap it out with the mocked service.


There are probably several tools that do what httpstat.us does, but I've found it works well and has most if not all HTTP response codes covered.

To summarize, I use it for the following scenarios:

  • For QA testing when they need to test something that is hard to simulate (like the server being down in a dev or UAT environment)
  • When I'm working on a FE feature and the BE endpoint isn't ready yet, or when the BE service relies on another service that isn't ready yet
  • For testing how the FE (or BE) handles a slow endpoint
  • When I'm working on a BE feature and want to manually test how it handles different response statuses, as opposed to it being handled through integration tests
  • When I want to test how the BE handles different response statuses from a third party service

Next time you run into one of the scenarios above, consider using a tool like httpstat.us to assist with your development work and/or testing!

Aside from testing how your code handles different HTTP response statuses, something I see Node developers often struggle with is where all your code should go in a REST API (sometimes referred to as "project structure"). If you want to see how I structure my Express REST API's and learn where your different types of code like request logic, middleware, database calls, etc. should go, subscribe below to be sent an email with an explanation of that as well as a repo with that structure. You'll also get all my future posts delivered directly to your inbox!

Subscribe for the explanation and repo!

No spam ever. Unsubscribe any time.