Handling Errors

1.Overview

Requests made to our APIs can result in several different error responses. The following document describes the recovery tactics and provides a list of error values with a map to the most common recovery tactic to use.

2. Error Responses

The following illustrates a standardized error message format that follows the Problem Details for HTTP APIs specification (RFC 7807 / RFC 9457).

{
  "type": "about:blank",
  "title": "Bad Request",
  "status": 400,
  "detail": "bad building code",
  "instance": "/hanger-selector/hangers",
  "errors": [
    {
      "name": "Building Code",
      "reason": "bad building code"
    }
  ]
}

Top-level fields

type: A URI reference identifying the problem type, "about:blank" means no specific URI is provided
title: A short, human-readable summary of the problem.
status: The HTTP status code generated by the server.
detail: A human-readable explanation of the error specific to this occurrence.
instance: A URI reference that identifies the specific occurrence of the problem.

Extended field

errors: A custom extension to provide more granular details, often used for validation errors. It’s an array of objects where each item usually contains:
- name: The field or parameter that caused the error.
- reason: The field or parameter that caused the error.

3.Error based on HTTP Code

HTTP Status Code	Name	Description	Suggestion Action
400	Bad Request	The server cannot process the request due to client-side errors (e.g., invalid input, missing required fields).	Verify input parameters, ensure request body and query strings follow the API specification.
401	Unauthorized	The request lacks valid authentication credentials.	Provide a valid access token.
403	Forbidden	The server understands the request but refuses to authorize it.	Check user permissions/roles. Contact the admin if access is required.
404	Not Found	The requested resource could not be found on the server.	Confirm the endpoint URL is correct. Retry with valid values.
500	Internal Server Error	A generic error occurred on the server side.	Retry later, and if persistent, report to the development team with logs.
503	Service Unavailable	The server is temporarily unable to handle the request (overloaded or down for maintenance).	Retry after some time.