Content for  TS 29.501  Word version:  19.0.0

When an error occurs that prevents the NF/NF service acting as an HTTP server from successfully fulfilling the HTTP request, the NF/NF service shall map an application error to the most similar 4xx/5xx HTTP status code as defined in clause 5.2.7 of TS 29.500.

When the HTTP status code is not enough for the NF/NF service acting as an HTTP client to determine the cause of the error, the NF/NF service acting as an HTTP server should provide additional application related error information, by including in the response body a representation of a "ProblemDetails" data structure according to RFC 9457 that provides additional details of the error. The definition of the general "ProblemDetails" data structure from RFC 9457 is specified in clause 5.2.4.1 of TS 29.571. The "ProblemDetails" data structure is a JSON object, as defined in RFC 9457, and contains the following attributes:

1. "type" - a URI reference according to RFC 3986 that identifies the problem type;
2. "title" - a short, human-readable summary of the problem type that should not change from occurrence to occurrence of the problem;
3. "status" - the HTTP status code for this occurrence of the problem;
4. "detail" - a human-readable explanation specific to this occurrence of the problem; and
5. "instance" - a URI reference that identifies the specific occurrence of the problem.

A particular API may define additional attributes that provide more information about the error. The following additional attributes are generic extensions defined for the 3GPP 5GC APIs:

1. "cause"- a machine-readable application error cause specific to this occurrence of the problem; and
2. "invalidParams" - invalid parameters causing a request to be rejected.

The "cause" attribute should be included and provide application-related error information, if available. Application error causes should be defined in 5GC SBI APIs specifications, using the UPPER_WITH_UNDERSCORE case convention specified in clause 5.1.1. EXAMPLE 1: The "invalidParams" attribute should be used to report invalid parameters when a request is rejected due to invalid parameters. All the application error causes supported by an API should be defined in a specific clause "Application Errors" under the "Error Handling" clause specified for the API. The application error causes that a specific service operation may respond should be further listed in the table defining the data structure supported by the response body, with the associated HTTP error status code. To enable a SEPP or an SCP for Indirect Communications to provide error details in error responses they originate, all service operations should support returning error responses including a representation of a "ProblemDetails" data structure. If additional application specific information is required in the error responses, the API should support returning the additional applicative information as specified in clause 4.8.3. The NF/NF service that generates the HTTP response shall include in the HTTP response a "Content-Type" header field set to:

• "application/problem+json", if the response includes a content containing the "ProblemDetails" (or extended ProblemDetails, see clause 4.8.3) data structure; or
• "application/json", if the response includes a content containing an application-specific data structure.

For a service operation that returns "ProblemDetails" in error responses in a given release, if in a later release it is required to provide additional application specific information in the error responses, the API should be modified to return an Extended-ProblemDetails data type by reusing the "ProblemDetails" common data type, as specified in clause 5.3.17, to keep the API backward compatibility. The "Content-Type" header shall be set to "application/problem+json" for the error response with the content containing the Extended-ProblemDetails data type define above. EXAMPLE:

• an "AdditionInfo<ServiceOperation>" structured data type containing the additional information to be returned, as specified in clause 5.2.4.2:

• a "ProblemDetails<ServiceOperation>" data type as combination of "ProblemDetails" common data type and "AdditionInfo<ServiceOperation>" data type define above, as specified in clause 5.2.4.5:

  Example OpenAPI specification of ProblemDetails<ServiceOperation> data type, as specified in clause 5.3.10:

components:
  schemas:
    ProblemDetails<ServiceOperation>:
      allOf:
      - $ref: 'TS29571_CommonData.yaml#/components/schemas/ProblemDetails'
      - $ref: '#/components/schemas/AdditionInfo<ServiceOperation>'

Example OpenAPI specification of an error response returning ProblemDetails<ServiceOperation> data type:

  responses:
    '504':
      description: Gateway Timeout
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails<ServiceOperation>'