2. Tutorials
  3. hapi — How to Set Response Status Code

hapi — How to Set Response Status Code

Within previous tutorials throughout this hapi series, you’ve seen a lot functionality related to the server itself, requests and authentication. This guide is the first one geared towards responses and precisely shows you how to set the response status code that follows the RFC.

Before diving into the details, have a look at the series outline and find posts that match your interests and needs.

hapi Series Overview

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. How to Run Separate Frontend and Backend Servers Within a Single Project
  2. How to Use Server Labels
  3. How to Correctly Stop Your Server and Close Existing Connections
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Views in hapi 9 (and above)
  2. How to Render and Reply Views
  3. How to Reply and Render Pug Views (Using Pug 2.0)
  4. How to Create a Dynamic Handlebars Layout Template
  5. Create and Use Handlebars Partial Views
  6. Create and Use Custom Handlebars Helpers
  7. Specify a Different Handlebars Layout for a Specific View
  8. How to Create Jade-Like Layout Blocks in Handlebars
  9. Use Vue.js Mustache Tags in Handlebars Templates
  10. How to Use Multiple Handlebars Layouts
  1. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. Query Parameter Validation With Joi
  2. Path Parameter Validation With Joi
  3. Request Payload Validation With Joi
  4. Validate Query and Path Parameters, Payload and Headers All at Once on Your Routes
  5. Validate Request Headers With Joi
  6. Reply Custom View for Failed Validations
  7. Handle Failed Validations and Show Errors Details at Inputs
  8. How to Fix AssertionError, Cannot validate HEAD or GET requests
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Getting Started With Testing Using Lab and Code
  2. Run Tests with Assertions using Code
  3. Test Route Handlers by Injecting Requests
  4. Inject Request Payload, Headers and Parameters While Testing Route Handlers
  1. Zero-Downtime Deployments Using PM2

Hapi Default: 200 OK

By default, hapi uses the 200 OK status for non-error responses that are created using the reply interface. Usually, that’s absolutely fine and your consuming clients will work properly. Nonetheless, there are situations where you want to provide more precise status codes, like when creating new documents (201 Created) within your database or in error scenarios. Let’s jump right into the topic and have a look on how to set your desired status code for responses.

Set Response Status Code

Using the reply interface with a usual JavaScript object will create a response that can be further customized. The interesting part is the .code(code) method that adjusts the response’s status.

hapi v17

server.route({  
  method: 'GET',
  path: '/',
  config: {
    handler: (request, h) => {
      const data = { key: 'value' }

      return h.response(data).code(201)
    }
  }
})

hapi v16

server.route({  
  method: 'GET',
  path: '/',
  config: {
    handler: (request, reply) => {
      const data = { key: 'value' }

      reply(data).code(201)
    }
  }
})

Let’s assume a client sends a request with payload and you’ve created a new object within the database based on the client’s information. Now you want to indicate that the request was handled successfully by using the response status code 201 Created and as payload you’re sending the newly created object.

The code snippet above mainly illustrates the response creation with the help of reply and afterwards updates the status code to 201. Actually, that’s all you need to do when setting your status code of choice.

Error Status Codes with Boom

Hapi allows you to benefit from their library that creates HTTP-friendly error objects: called Boom. With the help of boom, you’re creating consistent error objects with correct HTTP status codes. Furthermore, you can add and send a custom error message with more specific information about the problem you’ve encountered while processing the request.

Using a boom error object as the response will automatically set the response status code. boom provides methods to easily create the response object for each HTTP status equal to 400 and above.

hapi v17

const Boom = require('boom')

server.route({  
  method: 'GET',
  path: '/',
  config: {
    handler: function (request, h) {
      throw Boom.notFound('Cannot find the requested page')
    }
  }
})

hapi v16

const Boom = require('boom')  
server.route({  
  method: 'GET',
  path: '/',
  config: {
    handler: function (request, reply) {
      reply(Boom.notFound('Cannot find the requested page'))
    }
  }
})

The example above leverages the .notFound(message) method of boom to create a 404 Not Found response. The custom message will be sent within the response payload. The response that is received on client side looks like this:

404 Not Found

{
  "statusCode": 404,
  "error": "Not Found",
  "message": "Cannot find the requested page"
}

The statusCode and error are available within the payload as well as your custom message.

Status Codes for Empty Response Payload

In situations where you don’t send any payload to your client, the 204 No Content status code is the correct choice. Actually, there are many clients (even browsers) that wait for status 200 OK in case the request was processed properly. That’s why hapi manages the balancing act of setting 200 OK as the default response status.

If you want to comply the RFC and send 204 No Content in situations where your response doesn’t contain any payload, configure your route to use the 204 status:

hapi v17

server.route({  
  method: 'GET',
  path: '/',
  config: {
    response: {
      emptyStatusCode: 204
    },
    handler: (request, h) => {}
  }
})

hapi v16

server.route({  
  method: 'GET',
  path: '/',
  config: {
    response: {
      emptyStatusCode: 204
    },
    handler: function (request, reply) {
      reply()
    }
  }
})

The example above illustrates a response without any payload and a 204 No Content status code.

In case you provide data to reply, hapi will use the proper 200 or any (error) code you defined for the response. Of course, you can also use reply().code(204) to send empty responses with a precise status code and skip the extra route configuration.

Outlook

Hopefully this guide helps and motivates you to set proper status codes within your future coding sessions. Actually, clients will benefit a lot from precise responses including status codes other than just 200 and 400. Especially in error situations you’re able to display detailed messages on what needs to be fixed to successfully request a resource.

We appreciate feedback and love to help you if there’s a question on your mind. Let us know in the comments or on twitter @futurestud_io.

Make it rock & enjoy coding!

Additional Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous