| 1 |
=============== |
| 2 |
Problem Details |
| 3 |
=============== |
| 4 |
|
| 5 |
.. versionadded:: 2.9.0 |
| 6 |
|
| 7 |
Problem details are a standardized way of providing machine-readable details of errors in HTTP |
| 8 |
responses as specified in `RFC 9457`_, the latest RFC at the time of writing. |
| 9 |
|
| 10 |
.. _RFC 9457: https://datatracker.ietf.org/doc/html/rfc9457 |
| 11 |
|
| 12 |
Usage |
| 13 |
----- |
| 14 |
|
| 15 |
To send a problem details response, the ``ProblemDetailsPlugin`` should be registered and then |
| 16 |
a ``ProblemDetailsException`` can be raised anywhere which will automatically be converted |
| 17 |
into a problem details response. |
| 18 |
|
| 19 |
.. literalinclude:: /examples/plugins/problem_details/basic_usage.py |
| 20 |
:language: python |
| 21 |
:caption: Basic usage of the problem details plugin. |
| 22 |
|
| 23 |
You can convert all ``HTTPExceptions`` into problem details response by enabling the flag in the ``ProblemDetailsConfig.`` |
| 24 |
|
| 25 |
.. literalinclude:: /examples/plugins/problem_details/convert_http_exceptions.py |
| 26 |
:language: python |
| 27 |
:caption: Converting ``HTTPException`` into problem details response. |
| 28 |
|
| 29 |
|
| 30 |
You can also convert any exception that is not a ``HTTPException`` into a problem details response |
| 31 |
by providing a mapping of the exception type to a callable that converts the exception into a |
| 32 |
``ProblemDetailsException.`` |
| 33 |
|
| 34 |
.. tip:: This can be used to override how the ``HTTPException`` is converted into a problem details response as well. |
| 35 |
|
| 36 |
.. literalinclude:: /examples/plugins/problem_details/convert_exceptions.py |
| 37 |
:language: python |
| 38 |
:caption: Converting custom exceptions into problem details response. |
| 39 |
|
| 40 |
.. warning:: If the ``extra`` field is a ``Mapping``, then it's merged into the problem details response, otherwise it's included in the response with the key ``extra``. |