HTTP Response Codes
Common API response 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:
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):
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'