Advanced dev
Designing a Robust JSON API
  •  

Standardizing Errors and Status Codes

Before we can start designing any API endpoints, we need to create a standard for returning error messages and what status codes are being used. Above all, error handling should be consistent across the entire application. This allows other developers to easily reason about what might be going wrong in their codebases.

For validation errors that need to be sent back to the client, we'll use status code 422 and errors in the following format:

{
  "errors":{
    "body": [
      "can't be empty"
    ]
  }
}

Having the errors keyed by the field name allows the frontend to highlight the specific field that is breaking.

Other status codes:

401 for Unauthorized requests, when a request requires authentication but it isn't provided

403 for Forbidden requests, when a request may be valid but the user doesn't have permissions to perform the action

404 for Not found requests, when a resource can't be found to fulfill the request