API Error Reporting Guidelines¶

Introduction¶

Our goal is to harmonize the reporting of errors for API clients. The representation of an error should be no different than the representation of any resource, just with its own set of fields. In addition to use HTTP error codes, which are often too coarse to guide the API client to solve the problem, we apply an extensible approach for the possible wide range of error types. This set of rules harmonizes all APIs reporting errors to API clients. The interoperability of the format reduces efforts for the API producer as well as on the API client side.

Most of the time in development is spent for reading and understanding the code. Therefore, a fast understanding of reported errors of an API is very important. The API error guidelines assure that enough information to handle client-side and server-side errors in a consistent way such as unauthorized, retry timespans, or a maximum of calls per timespan will be provided and the developers of the API clients have a consistent way to handle reported errors simpler.

This page provides guidance on how an API developer must implement an error handling approach to handle reported errors of the APIs. If the API reports errors as it is covered in this page, an API client is able to inspect the error and find an appropriate solution.

API MUST use official HTTP status codes as intended [300]¶

An API MUST consistently use official HTTP status codes only with their intended semantics. The official HTTP status codes are defined and registered at:

• RFC 9110 - HTTP Semantics (obsoletes 7232, 7235)
• RFC 2616: Hypertext Transfer Protocol - HTTP/1.1, section 6.1.1 “Status code and Reason Phrase”
• IANA Status Code Registry
• RFC 6585 - HTTP: Additional Status Codes

The rule 301 lists the supported error codes. The different 4xx HTTP status codes are used for errors caused by API client side and 5xx HTTP status codes reports server side errors.

API SHOULD only use most common HTTP status codes [301]¶

An API SHOULD use the most commonly used codes as these are best understood. You SHOULD avoid less commonly used codes or own error codes that may create misconceptions and misunderstandings due to less familiar semantics. If the API has to report a HTTP error code which is not covered in the list below, the API specification MUST define the semantic of the error code.

Response codes MUST be documented in the API documentation, if the API reports or supports these error types. The official HTTP status codes are grouped in the following four classes. These HTTP status codes need to be used consistently with their intended semantics as per the RFC standards.

Client Error 4xx Status Codes [301.3]¶

Server Error 5xx Status Codes [301.4]¶

API SHOULD use most specific HTTP status code for error [302]¶

An API SHOULD use the most specific HTTP status code when returning information about the request processing state or reported error situations.

API SHOULD not expose stack traces of the error [303]¶

An API reports errors, but it SHOULD NOT expose stack traces. Firstly, stack traces are not part of an API specification, secondly API clients should never rely on stack traces to change a request. Moreover, stack traces expose sensitive information of the code and its dependencies that partners and third parties are not allowed to receive and may disclose unintended insights about vulnerabilities to attackers.

Additionally, the other property of a JSON error object can expose sensitive information of the code and its dependencies. Therefore the reported errors SHOULD be evaluated in a threat and risk analysis if the reported information offers an attack vector on the Xcelerator service.

API SHOULD report problems with an errors object [304]¶

Errors SHOULD be described in the error objects. In the response, the top level member is the errors object for API. The errors collection MUST not be empty but contain at least one error object.

With the error object, the raised problem is communicated to the API client to react accordingly. errors are intended to explain 4xx or 5xx HTTP status codes in more detail. The errors collection SHOULD report all known and identified problems from the API to the API client. The list of errors contains all known occurred errors on the backend. The objective is to avoid a step-wise exploration of issues until all are fixed. Of course in case of a distributed system not all errors are known in advance, but what could be validated, SHOULD be reported to the API client.

Error object SHOULD be represented according to the defined structure fields [305]¶

Each error object within the errors array MUST NOT be empty and MUST contain at least one of the following attributes:

An API MAY provide additional attributes.

The links resource object MAY contain the following members:

• about: MUST provide a URI that redirects to further details about this particular occurrence of the error. When opened, this URI SHOULD return a human-readable description of the error for the developer to investigate.
• type: MUST provide a URI that identifies the type of error that this particular error belongs to. The URI points to a human-readable explanation of the error type for the developer to investigate.

Here is an example of a simple error response.

{
  "errors": [
    {
      "code":   "0x80003033"
    }
  ]
}

In the above example HTTP header already includes status and title, so there is no need of repetition.

In case the application wants to point in the error object to the primary source of the problem, the property source MAY be used. The source object SHOULD include one of the following members or be omitted:

• pointer: a RFC6901 JSON Pointer to the value in the request document that caused the error (for example, "/data" for a primary data object, or "/data/attributes/title" for a specific attribute). This MUST point to a value in the request document that exists; if it doesn’t, the API client SHOULD simply ignore the pointer.
• parameter: a string that indicates which URI query parameter caused the error.
• header: a string that indicates the name of the header property which caused the error.

Here is an example of a detailed error response.

{
  "errors": [
    {
      "id": "eec33bf0-6bcc-4813-ae7e-0a70e8e53c3b",
      "code": "0x00000001",
      "status": 415,
      "title": "Unsupported Media Type",
      "detail": "The requested content type is not supported",
      "source": {
        "header": "content-type"
      },
      "links": {
        "about": "https://applicationx.siemens.net/validation-error/overview/#content-type",
      }
    },
    {
      "id": "e043cedd-600c-468c-8563-d4e591e3ba89",
      "code": "0x30005553",
      "detail": "the device name must not include any other characters than a-z, A-Z, 0-9, - and _",
      "title": "Unprocessable Content",
      "source": {
        "pointer": "/device/attributes/deviceName"
      },
      "links": {
        "about": "https://applicationx.siemens.net/validation-error/overview/#devices",
      }
    },
    {
      "id": "fd5864bd-3233-4f8d-9da2-734910be43bb",
      "code":   "0x80003033",
      "status": 410,
      "detail": "The device with name is already gone"
    }
  ]
}