[ADP-403] Problem Type Design

Core Principles

1. MUST be a human-readable URI reference.

   TIP

   According to RFC 9457, the type field must be a relative or absolute URI. In practice, the type should be designed to be human-readable. Avoid opaque or meaningless URIs such as /1234088abc—prefer descriptive, hierarchical URIs.

2. When the publication location is uncertain, MAY use a relative URI reference. Currently we are not publishing any problem types, so we SHOULD use relative URIs.
3. General Problem Types: SHOULD maximize reuse of existing problem types.
4. Avoid about:blank: MUST NOT use about:blank for identical
5. Refer to ADP-406 for more examples of types.
6. SHOULD provide the type list in the OpenAPI document with the example.

Design Process

1. Review existing HTTP status codes, referencing ADP-200.
2. For exact matches, use 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.

• Add the new problem type into API document(which is OpenAPI spec in our case) in the example field.

6. Add extra field specific to the problem type if necessary. For example, out-of-stock problem type may have productId and stockCount fields in the problem object.
7. Use the errors field to describe multiple errors.

[DEPRECATED] Subtype/extraType Design

Note: This section is historical. The use of an extraType field is now discouraged. All problem classification should be done via the type URI, using hierarchical or descriptive paths as needed.

Previously, it was considered to introduce an extraType field for more granular subtypes. The recommended practice now is to encode all specificity into the type URI, for example:

{
  "type": "https://example.com/problems/authentication-error/user-not-found",
  "title": "Authentication Error",
  "status": 409,
  "detail": "Your session has expired due to JWT",
  "errors": []
}

Do not use extraType. Always use a descriptive type URI to represent all levels of problem classification.

References

• Problem Details Registry
• RFC 9457

Changelog

• 2025.05.09: Remove product specific type design