[ADP-365] Custom Status Code

Guidance

Avoiding Custom Status Codes

MUST NOT create custom HTTP status codes.
SHOULD use standard HTTP status codes as defined in RFC 7231/RFC 9110 and other relevant RFCs.

Using Problem Details

SHOULD use Problem Details (RFC 9457) to provide more specific error information when standard status codes are not sufficiently descriptive.
MAY define custom problem types to represent application-specific errors. See ADP-403: Problem Type Design for guidance on custom problem types.

Example

http

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/invalid-user-input",
  "title": "Invalid User Input",
  "status": 400,
  "detail": "The provided email address is not in a valid format.",
  "instance": "/users/create"
}

Documentation

MUST document all used HTTP status codes and their associated Problem Details in the API documentation.
SHOULD provide examples of error responses in the API documentation.
SHOULD include error responses in the public OpenAPI problems.yaml for easy sharing, please refer to ADP-767.

Rationale

Custom status codes can lead to interoperability issues and confusion for API consumers. By using standard status codes and Problem Details, we ensure better compatibility and provide a more standardized way of communicating errors and exceptional situations.

[ADP-365] Custom Status Code ​

Guidance ​

Avoiding Custom Status Codes ​

Using Problem Details ​

Example ​

Documentation ​

Rationale ​

References ​