Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Common API

...

The Common API Specification lists only those error codes for which an implementer should be prepared to handle for business reasons and which are closely linked to the business logic implemented in the API.

Examples of business specific response codes for a request to delete a pending payment:

Status Code

Message

Example

200

OK

Payment has been deleted

201

Created

Payment is marked for deletion

404

Not found

Payment does not exist

Highly standardized and technical error codes (e.g. 5xx server errors, security related codes, bad request) need not be listed explicitly, because any implementer needs to do standard HTTP error handling anyway.

Examples of technical response codes for a request to delete a pending paymentresponse code approach is aligned to RFC7807 for client (4xx) and server errors (5xx). RFC7807 defines a way to carry machine-readable details of errors in a HTTP response (JSON Problem type).

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

The following client and server error codes (4xx, 5xx) are defined in the Common Data Model according to RFC7807 and therefore can be used in all Common APIs to deliver problems details:

Status Code

Message

400

Bad Request

401

Unauthorized

403

Forbidden

404

Not Found

405

Method Not Allowed

500

Internal Server Error

501

Not Implemented

503

Service Unavailable

Response definition example:

Code Block
    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 correlates 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'

Common Error Schema (problem+json format):

Code Block
    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'