# 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).


```json
{
  "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. |