API Responses and HTTP Response Codes

Intro

Common API response code approach is aligned to RFC9110 for successful responses (2xx), client (4xx), and server errors (5xx). RFC7807 defines a way to carry both human- and machine-readable details of errors in an HTTP response (JSON Problem Details type).

This basically means, that not only the pure HTTP status codes (2xx, 4xx, 5xx) are returned, but also a JSON body with individual additional information, why an error occurred.

The success response codes (2xx) and client and server error codes (4xx, 5xx) listed at this page are defined in the Common Data Model according to RFC7807/RFC9110 and therefore can be used in all Common APIs to deliver problem details.

API Responses and HTTP Response Codes

This page provides information about response codes transferred by STFI Common APIs. It is aligned with the standardized response handling process, which is defined by RFC 9110: HTTP Semantics and RFC 7801: Problem Details for HTTP APIs. This page covers both HTTP status codes and the JSON problem details extension since SFTI uses both parts to provide descriptive API responses. In the provided example we show how those parts are brought together as suggested by RFC 9910 and RFC 7801.

Status Codes

First, we provide all HTTP status codes which are used by at least one common API. Right now all common APIs support the same set of status codes. These response codes are standardized in RFC 9910 Section 15. Status Codes and indicate in which way a request to the API was processed. In the following table, we state the response codes and describe their intended usage.

Error Code	Meaning	Description
1xx	Informational
2xx	Successful
200	OK	The 200 (OK) status code indicates that the request has succeeded. The content sent in a 200 response depends on the request method. For more details, we refer to Table 6 of RFC 9110 Section 15.3.1.
201	Created	The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created.
202	Accepted	The 202 (Accepted) status code indicates that the request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility in HTTP for re-sending a status code from an asynchronous operation.
204	No Content	The 204 (No Content) status code indicates that the server has successfully fulfilled the request and that there is no additional content to send in the response content. Metadata in the response header fields refer to the target resource and its selected representation after the requested action was applied.
3xx	Redirection
4xx	Client Error
400	Bad Request	The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
401	Unauthorized	The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.
403	Forbidden	The 403 (Forbidden) status code indicates that the server understood the request but refuses to fulfill it. A server that wishes to make public why the request has been forbidden can describe that reason in the response content (if any). [If any data about the existance of a resource should not be exposed (e.g. due to security concerns), the 404 error code can be returned instead.]
404	Not Found	The 404 (Not Found) status code indicates that the origin server did not find a current representation for the target resource or is not willing to disclose that one exists.
405	Method Not Allowed	The 405 (Method Not Allowed) status code indicates that the method received in the request-line is known by the origin server but not supported by the target resource.
5xx	Server Error
500	Internal Server Error	The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.
501	Not Implemented	The 501 (Not Implemented) status code indicates that the server does not support the functionality required to fulfill the request.
503	Service Unavailable	The 503 (Service Unavailable) status code indicates that the server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

For more details about these response codes, we refer to the detailed descriptions of RFC 9110.
If no suitable recommendation for an HTTP response code is given on this page, we also ask you to use the standardized response codes as in RFC 9110.

JSON Problem Details Extension

Since status codes only transfer limited and fixed information about the API process, RFC 7801: Problem Details for HTTP APIs aims to address this issue and defines a problem detail object for HTTP APIs. All common APIs supplement status codes (except 2xx) with this human-readable problem detail using the JSON format object (Content-Type: application/problem+json). In detail, a problem detail JSON object must provide the following members (see RFC 7801):

• type (string) - A URI reference that identifies the problem type.
• title (string) - A short, human-readable summary of the problem type.
• detail (string) - A human-readable explanation specific to this occurrence of the problem.
• instance (string) - A URI reference that identifies the specific occurrence of the problem.

For more details, please refer to the Examples section and follow RFC 7801.

HTTP Status Code Response Conventions

Error Responses
For security reasons, we suggest to response with 404 error code messages only nevertheless which kind of error is occurred. However, if devices/network components are not able to send unified error messages it might be acceptable to But keep in mind that this behavior might lead to serious security issues.

General Responses
For non-error responses we include business-case examples to the specified response objects showing how specific status codes are used. So if one is uncertain which response code to use, these examples can be used as a reference and should give an insight how status codes are handled within the Common APIs.

---

Example

In this section, we provide a full example of a common API response. The Response is defined as follows:

standard400:
    headers:
        Content-Type:
            schema:
                type: string
                description: 'application/problem+json; charset=utf-8 according to RFC7807'
        Content-Language:
            schema:
                type: string
                description: 'Response language - always en'
        X-Correlation-ID:
            schema:
                type: string
                description: Client defined ID from request to correlate HTTP requests between a client and server.
        description: Bad Request - The server cannot or will not process the request due to something that is perceived to be a client error as malformed request syntax.
        content:
            application/problem+json:
                schema:
                    $ref: '#/components/schemas/commonErrorResponse'

The content of the response is implemented using a reference. The reference in problem+json format is defined as follows:

commonErrorResponse:
    title: Common Error Response
    type: object
    properties:
        type:
            $ref: '#/components/schemas/commonErrorType'
        title:
            type: string
            example:
                This is the general problem description
        detail:
            type: string
            example:
                Detailed problem description with respect to the current request
        instance:
            type: string
            example:
                path/to/corresponding/resource


commonErrorType:
    title: Common Error Type
    description: Error Types for commonErrorResponse.
    type: string
    enum:
        - /problems/INVALID_PAYLOAD
        - /problems/MALFORMED_PAYLOAD
        - /problems/INVALID_TOKEN
        - /problems/EXPIRED_TOKEN
        - /problems/INSUFFICIENT_PRIVILEGES
        - /problems/NO_ACCESS_TO_RESOURCE
        - /problems/RESOURCE_DOES_NOT_EXIST
        - /problems/RESOURCE_NOT_READY
        - /problems/RESOURCE_TOO_LARGE
        - /problems/WRONG_METHOD
        - /problems/OPERATION_NOT_ALLOWED
        - /problems/TECHNICAL_ERROR
        - /problems/NOT_IMPLEMENTED
        - /problems/SERVICE_UNAVAILABLE
    example: '/problems/TECHNICAL_ERROR'