[ADP-403] Problem Type Design

Core Principles

1. URI Reference: MUST be a human-readable URI reference.
2. Relative URI: When uncertain about the problem's publication location or whether it has been published, MAY use a relative URI reference.

Design Process

1. Review existing HTTP status codes, referencing ADP-200.
2. For exact matches, use type: about:blank or the URI reference conversion of the HTTP status code (e.g., /problems/not-found).
3. Use the detail field to provide methods for correcting errors.
4. If there is no matching status, consult the predefined problem type list.
5. Propose new types when necessary, ensuring they are general enough.
6. Use the errors field to describe multiple errors.

Subtype Design Proposal

In the proposal of RFC 9457, the requirement for the type must be general enough, but sometimes we may need more detailed subtypes for clients to handle accordingly. Clearly, in such cases, we should not use title or detail for correspondence. Therefore, we propose a new field design: subtype, also known as extra type.

The design concept is that ultimately, a URI reference pointing to that subtype can be formed by combining the problem domain + problem type + / + extra type, for example: https://apidoc.alive.dev/problems/not-found/user-not-found.

• MAY introduce the extraType field to enhance description

  {
    "type": "https://example.com/problems/authentication-error",
    "title": "Authentication Error",
    "extraType": "request-timeout-to-third-party",
    "status": 409,
    "detail": "Your session has expired due to JWT",
    "errors": []
  }

• extraType SHOULD correspond one-to-one with error details.

• extraType MAY be product-specific.

RFC 9457 Compliance Guidelines

1. Problem types MUST be general, not product-specific.
2. SHOULD maximize reuse of existing problem types.
3. Use about:blank when HTTP status codes are sufficient. Refer to ADP-402.
4. Refer to ADP-406 for more examples of types.

References

• Problem Details Registry
• RFC 9457