Tech-invite3GPPspecsSIPRFCs
Overview21222324252627282931323334353637384‑5x

Content for  TS 29.500  Word version:  16.4.0

Top   Top   Up   Prev   Next
1…   5…   5.2.3   5.2.4…   6…   6.4…   6.5…   6.6…   6.7…   6.10…   6.11…   A…

 

5.2.4  HTTP error handling
HTTP/2 connection error and stream error shall be supported as specified in clause 5.4 of IETF RFC 7540.
Guidelines for error responses to the invocation of APIs of NF services are specified in clause 4.8 of TS 29.501. API specific error responses are specified in the respective technical specifications.
5.2.5  HTTP/2 server push
HTTP/2 Server Push as specified in clause 8.2 of IETF RFC 7540 may be supported and may be used by a NF Service Producer to proactively push resources to a NF Service Consumer, see clause 4.9.5 of TS 29.501.
A NF Service Consumer may choose to disable HTTP/2 Server Push by setting SETTINGS_ENABLE_PUSH to 0, as specified in clause 8.2 of IETF RFC 7540.
Up
5.2.6  HTTP/2 connection management
The HTTP request / response exchange mechanism as specified in clause 8.1 of IETF RFC 7540 shall be supported between the 3GPP NFs. An HTTP/2 endpoint shall support establishing multiple HTTP/2 connections (at least two) towards a peer HTTP/2 endpoint. The peer HTTP/2 endpoint is identified by host and port pair where the host is derived from the target URI (see clause 6.1.1).
As per clause 8.1 of IETF RFC 7540 a HTTP request / response exchange fully consumes a single stream. When the HTTP/2 Stream IDs on a given HTTP/2connection is exhausted, an HTTP/2 endpoint, shall establish another HTTP/2connection towards that peer HTTP/2 endpoints.
The 3GPP NF shall take care to avoid simultaneous stream ID exhaustion on all the available HTTP/2 connections towards each peer.
The 3GPP NF shall support gracefully shutdown of a HTTP/2 connection by sending a GOAWAY frame with "Error Code" field set to "NO_ERROR (0x0)". The HTTP connection should remain "open" (by the sender and receiver of GOAWAY frame) until all in-progress streams numbered lower or equal to the last stream identifier indicated by the "Last-Stream-Id" field in the GOAWAY frame are completed. See clause 6.8 of IETF RFC 7540.
An NF acting as an HTTP/2 client shall support testing whether a connection is still active by sending a PING frame. An NF acting as an HTTP/2 server may test whether a connection is still active by sending a PING frame. An NF acting as an HTTP/2 client or server shall respond to received PING frames as specified in clause 6.7 of IETF RFC 7540. When and how often a PING frame may be sent is implementation specific but shall be configurable by operator policy. When HTTP server detects the connection failure, it shall follow connection error handling as defined in clause 5.4.1 of RFC 7540.
A PING frame shall not be sent more often than every 60 s on each path.
Up
5.2.7  HTTP status codesWord‑p. 27
5.2.7.1  General
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 clause 8.1.2.4 in IETF RFC 7540.
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.
HTTP status code
HTTP method
DELETE
GET
PATCH
POST
PUT
OPTIONS

100 Continue
N/A
N/A
N/A
N/A
N/A
N/A
200 OK (NOTE 1, NOTE 2)
SS
M
SS
SS
SS
M
201 Created
N/A
N/A
N/A
SS
SS
N/A
202 Accepted
SS
N/A
SS
SS
SS
N/A
204 No Content (NOTE 2)
M
N/A
SS
SS
SS
SS
300 Multiple Choices
N/A
N/A
N/A
N/A
N/A
N/A
303 See Other
SS
SS
N/A
SS
SS
N/A
307 Temporary Redirect
SS
SS
SS
SS
SS
SS
308 Permanent Redirect
SS
SS
SS
SS
SS
SS
400 Bad Request
M
M
M
M
M
M
401 Unauthorized
M
M
M
M
M
M
403 Forbidden
M
M
M
M
M
M
404 Not Found
M
M
M
M
M
M
405 Method Not Allowed
SS
SS
SS
SS
SS
SS
406 Not Acceptable
N/A
M
N/A
N/A
N/A
SS
408 Request Timeout
SS
SS
SS
SS
SS
SS
409 Conflict
N/A
N/A
SS
SS
SS
N/A
410 Gone
SS
SS
SS
SS
SS
SS
411 Length Required
N/A
N/A
M
M
M
SS
412 Precondition Failed
SS
SS
SS
SS
SS
N/A
413 Payload Too Large
N/A
N/A
M
M
M
SS
414 URI Too Long
N/A
SS (NOTE 3)
N/A
N/A
SS
N/A
415 Unsupported Media Type
N/A
N/A
M
M
M
SS
429 Too Many Requests
M
M
M
M
M
M
500 Internal Server Error
M
M
M
M
M
M
501 Not Implemented
SS
SS
SS
SS
SS
SS
503 Service Unavailable
M
M
M
M
M
M
504 Gateway Timeout
SS
SS
SS
SS
SS
SS


Up
5.2.7.2  NF as HTTP ServerWord‑p. 28
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 application errors 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 payload 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 payload body larger than the NF is able to process, the NF shall reject the HTTP request with the HTTP status code "413 Payload 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 a payload body ("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.
Protocol or application Error
HTTP status code
Description

INVALID_API
400 Bad Request
The HTTP request contains an unsupported API name or API version in the URI.
INVALID_MSG_FORMAT
400 Bad Request
The HTTP request has an invalid format.
INVALID_QUERY_PARAM
400 Bad Request
The HTTP request contains an unsupported query parameter in the URI. (NOTE 1)
MANDATORY_QUERY_PARAM_INCORRECT
400 Bad Request
A mandatory query parameter, or a conditional query parameter but mandatory required, for an HTTP method was received in the URI with semantically incorrect value. (NOTE 1)
OPTIONAL_QUERY_PARAM_INCORRECT
400 Bad Request
An optional query parameter for an HTTP method was received in the URI with a semantically incorrect value that prevents successful processing of the service request. (NOTE 1)
MANDATORY_QUERY_PARAM_MISSING
400 Bad Request
Query parameter which is defined as mandatory, or as conditional but mandatory required, for an HTTP method is not included in the URI of the request. (NOTE 1)
MANDATORY_IE_INCORRECT
400 Bad Request
A mandatory IE (within the JSON body or within a variable part of an "apiSpecificResourceUriPart" or within an HTTP header), or conditional IE but mandatory required, for an HTTP method was received with a semantically incorrect value. (NOTE 1)
OPTIONAL_IE_INCORRECT
400 Bad Request
An optional IE (within the JSON body or within an HTTP header) for an HTTP method was received with a semantically incorrect value that prevents successful processing of the service request. (NOTE 1)
MANDATORY_IE_MISSING
400 Bad Request
A mandatory IE (within the JSON body or within the variable part of an "apiSpecificResourceUriPart" or within an HTTP header), or conditional IE but mandatory required, for an HTTP method is not included in the request. (NOTE 1)
UNSPECIFIED_MSG_FAILURE
400 Bad Request
The request is rejected due to unspecified client error. (NOTE 2)
NF_DISCOVERY_FAILURE
400 Bad Request
The request is rejected by the SCP because no NF Service Producer can be found matching the NF service discovery factors.
INVALID_DISCOVERY_PARAM
400 Bad Request
The request is rejected by the SCP because it contains an unsupported discovery parameter (i.e. unknown 3gpp-Sbi-Discovery-* header). (NOTE 1)
RESOURCE_CONTEXT_NOT_FOUND
400 Bad Request
The notification request is rejected because the callback URI still exists in the receiver of the notification, but the specific resource context identified within the notification payloadis not found in the NF service consumer.
MODIFICATION_NOT_ALLOWED
403 Forbidden
The request is rejected because the contained modification instructions attempt to modify IE which is not allowed to be modified.
SUBSCRIPTION_NOT_FOUND
404 Not Found
The request for modification or deletion of subscription is rejected because the subscription is not found in the NF.
RESOURCE_URI_STRUCTURE_NOT_FOUND
404 Not Found
The request is rejected because a fixed part after the first variable part of an "apiSpecificResourceUriPart" (as defined in clause 4.4.1 of TS 29.501) is not found in the NF.
This fixed part of the URI may represent a sub-resource collection (e.g. contexts, subscriptions, policies) or a custom operation. (NOTE 5)
INCORRECT_LENGTH
411 Length Required
The request is rejected due to incorrect value of a Content-length header field.
NF_CONGESTION_RISK
429 Too Many Requests
The request is rejected due to excessive traffic which, if continued over time, may lead to (or may increase) an overload situation.
INSUFFICIENT_RESOURCES
500 Internal Server Error
The request is rejected due to insufficient resources.
UNSPECIFIED_NF_FAILURE
500 Internal Server Error
The request is rejected due to unspecified reason at the NF. (NOTE 3)
SYSTEM_FAILURE
500 Internal Server Error
The request is rejected due to generic error condition in the NF.
NF_FAILOVER
500 Internal Server Error
The request is rejected due to the unavailability of the NF, and the requester may trigger an immediate re-selection of an alternative NF based on this information.
The SCP may also use it, as indication for re-selection.
NF_SERVICE_FAILOVER
500 Internal Server Error
The request is rejected due to the unavailability of the NF service, and the requester may trigger an immediate re-selection of an alternative NF service based on this information.
The SCP may also use it, as indication for re-selection.
NF_CONGESTION
503 Service Unavailable
The NF experiences congestion and performs overload control, which does not allow the request to be processed. (NOTE 4)
TIMED_OUT_REQUEST
504 Gateway Timeout
The request is rejected due a request that has timed out at the HTTP client (see clause 6.11.2).
SCP_REDIRECTION
307 Temporary Redirect
308 Permanent Redirect
The request is redirected to a different SCP (see clause 6.10.9).


Up
5.2.7.3  NF as HTTP ClientWord‑p. 32
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 IETF 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 clause 6 of IETF RFC 7231.
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 payload in subsequent procedure.
    2. If mandatory information is expected from response payload in subsequent procedure, parse the payload following description in clause 6.2.1 of IETF RFC 7231 [11]. 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.
Up
5.2.8  HTTP/2 request retriesWord‑p. 33
All NF services expose APIs across the service based interfaces and the APIs operate on resources. Invocation of an API though a HTTP method may result in the change of state of a resource depending of the request type. When a HTTP/2 client sends a request and it does not receive a response or it experiences a delay, it does not guarantee that the HTTP/2 request has not been processed by the HTTP/2 server.
A HTTP/2 client may retry the same request that uses an idempotent method any time (see RFC 7231 clause 4.2.2).
Retrying a non-idempotent HTTP/2 request on the same resource before a response for the previous request is received may lead to state changes on the resource with unspecified behaviour. HTTP conditional requests, as specified in IETF RFC 7232 [24] may be used to avoid such situations.
An NF acting as an HTTP/2 client should also retry non-idempotent request if the request has not been processed, i.e. if the identifier of the stream corresponding to the request is larger than the Last-Stream-Id in a GOAWAY frame, or the REFUSED_STREAM error code is included in a RST_STREAM frame for the stream corresponding to the request as specified in clause 8.1.4 of IETF RFC 7540. API specific mechanisms as specified in respective technical specifications may be used for reconciling the state of resources, if the retry is attempted through a new TCP connection after a TCP connection failure.
The number of retry shall be limited. A client should always prefer to retry requests to an alternative server if the initial server is overloaded. In case of general overload situation where all possible servers are overloaded retry mechanisms should be disabled automatically.
Up
5.2.9  Handling of unsupported query parameters
Unless specified otherwise for an API, a NF Service Producer that receives an HTTP request with one or more unsupported (i.e. not comprehended) query parameters shall:
  1. for safe HTTP methods (e.g. HTTP GET request):
    • ignore the unsupported query parameters and respond to the request based on the rest of the request (e.g. other supported query parameters); or
    • reject the HTTP request as specified below for non-safe HTTP methods, e.g. based on other query parameters in the request or based on a response becoming very large;
  2. for non-safe HTTP methods:
    • reject the request with a 400 Bad Request including a ProblemDetails IE with:
      • the cause attribute set to INVALID_QUERY_PARAM;
      • the invalidParams attribute indicating the unsupported query parameters;
      • the supportedFeatures attribute listing the features supported by the NF Service Producer, if any, set as specified for HTTP responses in clause 6.6.2.
Up
5.3  Transport ProtocolWord‑p. 34
The Transmission Control Protocol as described in RFC 793 shall be used as transport protocol as required by HTTP/2 (see RFC 7540).
If a Network Function does not register any port number to the NRF then it shall be prepared to receive connections on default port numbers, i.e. TCP port 80 for "http" URIs and TCP port 443 for "https" URIs as specified in RFC 7540.
Up
5.4  Serialization Protocol
The JavaScript Object Notation (JSON) format as described in RFC 8259 shall be used as serialization protocol.
For transmitting large parts of opaque binary data along with JSON format, multipart messages shall be supported using:
  • A multipart/related media type;
  • 3gpp vendor specific content subtype; and
  • Cross-referencing from the JSON payload using the Content-ID field.
Use of multipart messages is documented in specific specifications.
5.5  Interface Definition Language
OpenAPI Specification [9] shall be used as Interface Definition Language (IDL) of SBI.

Up   Top   ToC