Content for  TS 29.500  Word version:  19.0.0

This clause describes the HTTP status codes usage on SBI. HTTP status codes are carried in ":status" pseudo header field in HTTP/2, as defined in Section 8.1.2.4 in RFC 9113. Table 5.2.7.1-1 specifies HTTP status codes per HTTP method which shall be supported on SBI. Support of an HTTP status code shall be:

• mandatory, which is marked in Table as "M". This means that all 3GPP NFs shall support the processing of the specific HTTP status code for the specific HTTP method, when received in a HTTP response message. In such cases the 3GPP NF shall also support the handling of the "ProblemDetails" JSON object with the Content-Type header field set to the value "application/problem+json" for HTTP status codes 4xx and 5xx, if the corresponding API definition in the related technical specification does not specify another response body for the corresponding status code;
• service specific, which is marked in Table as "SS" and means that the requirement to process the HTTP status code depends on the definition of the specific API; or
• not applicable, which is marked in Table as "N/A". This means that the specific HTTP status code shall not be used for the specific HTTP method within the 3GPP NFs.

A NF acting as an HTTP server shall be able to generate HTTP status codes specified in clause 5.2.7.1 per indicated HTTP method. A request using an HTTP method which is not supported by any resource of a given 5GC SBI API shall be rejected with the HTTP status code "501 Not Implemented". If the specified target resource does not exist, the NF shall reject the HTTP method with the HTTP status code "404 Not Found". If the NF supports the HTTP method for several resources in the API, but not for the target resource of a given HTTP request, the NF shall reject the request with the HTTP status code "405 Method Not Allowed" and shall include in the response an Allow header field containing the supported method(s) for that resource. If a received HTTP request contains unknown IEs, i.e. Information Elements within the JSON body, the NF may discard such IEs and shall process the rest of the request message, unless the schema definition of the received message prohibits the presence of additional IEs or constrains their types. There are cases (e.g. Nnrf_NFManagement API) where the receiver of certain HTTP requests needs to process unknown IEs (e.g. to store in NRF an NF Profile containing vendor-specific attributes, and send them in NFDiscovery results). If a received HTTP request contains IEs or query parameters not compliant with the schema defined in the corresponding OpenAPI specification, the NF should reject the request with the appropriate error code, e.g. "400 Bad Request (INVALID_MSG_FORMAT)", even when the failed IEs are defined as optional by the schema. If a received HTTP PATCH request contains a body with modification instruction(s) for unknown attribute(s) in addition to modification instruction(s) for known attribute(s), the NF shall:

1. implement all the modification(s) for known attribute(s) and unknown attribute(s) if explicitly specified in the corresponding specification of the API; or
2. otherwise, implement the modification(s) for known attribute(s) and discard those modification instruction(s) for unknown attribute(s). The NF may additionally indicate in the response the result of the execution of the PATCH request, i.e. which modification(s) are implemented and/or which modification(s) are discarded, using the "PatchResult" JSON object as defined in TS 29.571.

If the NF supports the HTTP method by a target resource but the NF cannot successfully fulfil the received request, the following requirements apply. A NF as HTTP Server should map status codes to the most similar 3xx/4xx/5xx HTTP status code specified in Table 5.2.7.1-1. If no such code is applicable, it should use "400 Bad Request" status code for errors caused by client side or "500 Server Internal Error" status code for errors caused on server side. If the received HTTP request contains unsupported content format, the NF shall reject the HTTP request with the HTTP status code "415 Unsupported Media Type". If the HTTP PATCH method is rejected due to unsupported patch document, the NF shall include the Accept-Patch header field set to the value of supported patch document media types for a target resource i.e. to "application/merge-patch+json" if the NF supports "JSON Merge Patch" and to "application/json-patch+json" if the NF supports "JSON Patch". If the received HTTP PATCH request contains both "JSON Merge Patch" and "JSON Patch" documents and the NF supports only one of them, the NF shall ignore unsupported patch document. If the received HTTP request contains content larger than the NF is able to process, the NF shall reject the HTTP request with the HTTP status code "413 Content Too Large". If the result of the received HTTP POST request used for a resource creation would be equivalent to the existing resource, the NF shall reject the HTTP request with the HTTP status code "303 See Other" and shall include in the HTTP response a Location header field set to the URI of the existing resource. Protocol and application errors common to several 5GC SBI API specifications for which the NF shall include in the HTTP response content a "ProblemDetails" data structure or application specific error data structure with the "cause" attribute indicating corresponding error are listed in Table 5.2.7.2-1.

Besides the HTTP Status Codes defined in the API specification, a NF as HTTP client should support handling of 1xx, 3xx, 4xx and 5xx HTTP Status Codes specified in Table 5.2.7.1-1, following the client behaviour in corresponding RFC where the received HTTP Status Code is defined. When receiving a not recommended or not recognized 1xx, 3xx, 4xx or 5xx HTTP Status Code, a NF as HTTP client should treat it as x00 status code of the class, as described in Section 15 of RFC 9110. If 100, 200/204, 300, 400 or 500 response code is not defined by the API specification, the client may follow guidelines below:

1. For 1xx (Informational):
   1. Discard the response and wait for final response.
2. For 2xx (Successful):
   1. Consider the service operation is successful if no mandatory information is expected from the response content in subsequent procedure.
   2. If mandatory information is expected from response content in subsequent procedure, parse the content following description in Section 15.2.1 of RFC 9110. If parse is successful and mandatory information is extracted, continue with subsequent procedure.
   3. Otherwise, consider service operation has failure and start failure handling.
3. For 3xx (Redirection):
   1. Retry the request towards the directed resource referred in the Location header, using same request method.
4. For 4xx (Client Error):
   1. Validate the request message and make correction before resending. Otherwise, stop process and go to error handling procedure.
5. For 5xx (Server Error):
   1. Stop process and go to error handling process.

The handling of unknown, unexpected or erroneous HTTP request message IEs shall provide for the forward compatibility of the HTTP APIs used for the service-based interfaces. Therefore, the sending HTTP entity shall be able to safely include in a message a new optional IE. Such an IE may also have a new type. A receiving HTTP entity shall behave as specified in clause 5.2.7.2. If a received HTTP response message contains unknown IEs (Information Elements within the JSON body), the NF may discard those IEs and it shall process the rest of the response message, as long as it is compliant with the OpenAPI schema definition of such response message. If a received HTTP response message contains IEs not compliant with the schema defined in the corresponding OpenAPI specification (e.g., because the schema of the response body prohibits the presence of additional IEs or constrains their types), the NF shall stop processing such response message and go to error handling process.

The SCP or SEPP shall be able to forward the HTTP status codes defined in Table 5.2.7.1-1 and Table 5.2.7.2-1 from HTTP Server to HTTP client. In addition, it shall be able to generate HTTP status codes to indicate failures during indirect communication (e.g. see clauses 6.10.3.2 and 6.10.6), error handling (see clause 6.10.8), detection and handling of loop path (see clause 6.10.10) and SCP or SEPP overload control (see clause 6.4) as defined in Table 5.2.7.4-1 and Table 5.2.7.4-2. If the SCP or SEPP detects a loop in the routing path of an HTTP request, it should reject the request with the HTTP status code "400 Bad Request (MSG_LOOP_DETECTED)". If the received HTTP request contains content larger than the SCP or SEPP is able to process, the SCP or SEPP shall reject the HTTP request with the HTTP status code "413 Content Too Large". An HTTP status code "429 Too Many Requests (NF_CONGESTION_RISK)" is sent, when the SCP or SEPP detects that a given NF Service Consumer is sending excessive traffic which, if continued over time, may lead to (or may increase) an overload situation in the SCP or SEPP. If the SCP or SEPP decides to redirect HTTP requests to another less loaded SCP or SEPP, it may send the HTTP status code "307 Temporary Redirect" or "308 Permanent Redirect" with the cause attribute set to "SCP_REDIRECTION" (see clause 6.10.9) / "SEPP_REDIRECTION" as defined in Table 5.2.7.4-2. The SCP or SEPP should map status codes to the most similar 3xx/4xx/5xx HTTP status code specified in Table 5.2.7.4-1 and Table 5.2.7.4-2. If no such code is applicable, it should use "400 Bad Request" status code for errors caused by client side or "500 Server Internal Error" status code for errors caused on server side.

As indicated in IETF RFC 3986, the URI syntax defines a set of characters (a subset of the URI allowed characters) as delimiters of syntax components; those characters are called "reserved" and should not be used in URI fields intended to convey generic data (e.g., in the value part of a query parameter, or in the URI path segments), since this would interfere with the original meaning (syntax) of those reserved characters. In addition, HTTP/2 request body parts encoded with media type "application/x-www-form-urlencoded" shall also escape reserved and unsafe characters, as described in OpenAPI Specification [9].

When a URI is composed in the 3GPP 5G APIs, the different components (e.g., path segments, values of query parameters, etc.) shall percent-encode the following "reserved" characters (see Section 2.1 of RFC 3986):

EXCLAMATION MARK (U+0021)	!
NUMBER SIGN (U+0023)	#
DOLLAR SIGN (U+0024)	$
AMPERSAND (U+0026)	&
APOSTROPHE (U+0027)	'
LEFT PARENTHESIS (U+0028)	(
RIGHT PARENTHESIS (U+0029)	)
ASTERISK (U+002A)	*
PLUS SIGN (U+002B)	+
COMMA (U+002C)	,
SOLIDUS (U+002F)	/
COLON (U+003A)	:
SEMICOLON (U+003B)	;
EQUALS SIGN (U+003D)	=
QUESTION MARK (U+003F)	?
COMMERCIAL AT (U+0040)	@
LEFT SQUARE BRACKET (U+005B)	[
RIGHT SQUARE BRACKET (U+005D)	]

The following characters (not listed as "reserved" in IETF RFC 3986) shall be percent-encoded:

QUOTATION MARK (U+0022)	"
PERCENT SIGN (U+0025)	%

SPACE (U+0020) character shall be escaped, either by percent-encoding it (as %20), or by replacing it with character PLUS SIGN (U+002B). The encoding of query parameters consisting of arrays of strings shall follow the guidelines indicated in clause 5.3.13 of TS 29.501 for the escaping of the COMMA (U+002C) characters. In addition, implementations may percent-encode other characters, such as:

LEFT CURLY BRACKET (U+007B)	{
RIGHT CURLY BRACKET (U+007D)	}

The receiving entity shall percent-decode the received URI as specified in Section 2.4 of RFC 3986. Percent-encoding of reserved characters in the URI fields as described in this clause shall also apply to JSON attributes defined as URI and to HTTP header parameters whose ABNF definition uses production rules defined as URI or path-absolute (e.g. prefix parameter of the 3gpp-Sbi-Target-apiRoot header).

When composing an HTTP/2 request body with media type "application/x-www-form-urlencoded", the OpenAPI Specification [9] requires that the encoding shall follow Section 8.2.1 of RFC 1866, which indicates: The following characters (not listed as "reserved" in IETF RFC 1738) shall be percent-encoded:

QUOTATION MARK (U+0022)	"
PERCENT SIGN (U+0025)	%
COMMA (U+002C)	,
LEFT SQUARE BRACKET (U+005B)	[
RIGHT SQUARE BRACKET (U+005D)	]
LEFT CURLY BRACKET (U+007B)	{
RIGHT CURLY BRACKET (U+007D)	}

In addition, implementations may also percent-encode any of the characters listed in clause 5.2.10.2.