# Problem Detail

The [`application/problem+json`](https://tools.ietf.org/html/rfc7807) (Problem Detail) **MUST** be used to communicate details about an error.

Problem Detail is intended for use with the HTTP status codes 4xx and 5xx. Problem Detail **MUST NOT** be used with 2xx status code responses.

At the minimum, any Problem Detail response **MUST** have the `title` and `detail` fields. `title` value **SHOULD NOT** change from occurrence to occurence of the problem, except for purposes of localization (e.g., using proactive content negotiation) [read more](https://tools.ietf.org/html/rfc7807#section-3.1)

### Example

```javascript
{
  "title": "Authentication required",
  "detail": "Missing authentication credentials for the Greeting resource."
}
```

> NOTE: `title` and `detail` fields **SHOULD NOT** be parsed to determine the nature of the error. Instead `type` **MUST** be used.

## Optional Fields

It **SHOULD** have the `type` field with the identifier of the error, besides it **MAY** have the `instance` field with the URI of the resource in question. If the Problem Detail response has the `status` field it **MUST** have the same value as HTTP Status code from of the response.

```javascript
{
  "type": "https://adidas-group.com/problems/scv/unauthorized",
  "title": "Authentication required",
  "detail": "Missing authentication credentials for the Greeting resource.",
  "instance": "/greeting",
  "status": 401
}
```

> NOTE: The `type` field is an identifier, and as such it **MAY** be used to denote additional error codes. Keep in mind that the identifier should be a URI.

## Additional Fields

If needed, the Problem Detail **MAY** include additional fields, refer to [RFC7807](https://tools.ietf.org/html/rfc7807) for details.

## Validation Errors

When necessary, a Problem Detail response **MAY** include additional error details about the problems that have occurred.

These additional errors **MUST** be under the `errors` collection and **MUST** follow the Problem Detail structure.

### Example

Request:

```
POST /my-resource HTTP/1.1
Content-Type: application/json

{
  "age": -32,
  "color": "cyan"
}
```

Response:

```
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.net/validation_error",
  "title": "Your request parameters didn't validate.",
  "instance": "/my-resource",
  "status": 400,

  "errors": [
    {
      "type": "https://example.net/invalid_params",
      "instance": "/age",
      "title": "Invalid Parameter",
      "detail": "age must be a positive integer"
    },
    {
      "type": "https://example.net/invalid_params",
      "instance": "/color",
      "title": "Invalid Parameter",
      "detail": "color must be 'green', 'red' or 'blue'"
    }
  ]
}
```

## Problem Detail and Content Negotiation

### Example

A request is made to retrieve a resource representation:

```
GET /greeting HTTP/1.1
Accept: application/hal+json
```

However, in order to make this request, the client needs to be authorized. Since the request is made without the authorization credentials the **401 Unauthorized** response is returned together with details using the `application/problem+json` media type:

```
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://adidas-group.com/problems/scv/unauthorized",
  "title": "Authentication required",
  "detail": "Missing authentication credentials for the Greeting resource.",
  "instance": "/greeting",
  "status": 401
}
```

## No Stack Traces or Server Logs

> *Problem details are not a debugging tool for the underlying implementation; rather, they are a way to expose greater detail about the HTTP interface itself.*
>
> *–* [*RFC7807*](https://tools.ietf.org/html/rfc7807)

A Problem Detail response **MUST NOT** contain a program stack trace or server log for debugging purposes. Instead, provide a `logref` field with reference to the particular server log.

## Working with Problem Detail

An API description **MAY** list all the error codes with which the API responds. The error responses **SHOULD** describre the error object model schema. It is **RECOMMENDED** to include examples of a possible error response. The error description and/or error example **MAY** list all the types of errors returned for a given error code.

## External resources

There are a whole plethora of libraries working with Problem Detail, for example, see [Zalando / Problem](https://github.com/zalando/problem) (Java).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://adidas.gitbook.io/api-guidelines/rest-api-guidelines/message/error-reporting.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.