[ADP-365] Custom Status Code

Guidance

Avoiding Custom Status Codes

MUST NOT create custom HTTP status codes.
TIP
RFC 9110 specifies that "Status codes are generic; they are potentially applicable to any resource, not just one particular media type, kind of resource, or application of HTTP. As such, it is preferred that new status codes be registered in a document that isn't specific to a single application."
While the HTTP status code list is extensible officially, we SHOULD NOT create custom codes on our own. This avoids potential conflicts if a new standard status code is later defined for the same purpose.
RFC 9457 provides guidance on why creating a separate numbering system for custom error codes is not recommended.
Therefore, although RFC 9110 allows for custom status codes, we disallow creating new status codes for specific applications to prevent ambiguity and maintain interoperability.
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.

References

Changelog

2025.01.16: Add reasoning for avoiding custom status code.

[ADP-365] Custom Status Code ​

Guidance ​

Avoiding Custom Status Codes ​

Using Problem Details ​

Example ​

Documentation ​

Rationale ​

References ​

Changelog ​