From 50573c78b92e25b466b71f8b4a1073391bd182ee Mon Sep 17 00:00:00 2001 From: GareArc Date: Wed, 10 Jun 2026 03:42:48 -0700 Subject: [PATCH] docs(openapi): state the ErrorBody field table in the contract module docstring --- api/controllers/openapi/_errors.py | 16 ++++++++++++---- 1 file changed, 12 insertions(+), 4 deletions(-) diff --git a/api/controllers/openapi/_errors.py b/api/controllers/openapi/_errors.py index dcadfce1e8..84b76091c3 100644 --- a/api/controllers/openapi/_errors.py +++ b/api/controllers/openapi/_errors.py @@ -2,10 +2,18 @@ ``ErrorBody`` is the only wire shape an /openapi/v1 endpoint may emit for a non-2xx response (RFC 8628 device-flow responses excepted — that shape is -mandated by the OAuth spec). ``OpenApiErrorFormatter`` is injected into -``ExternalApi`` so every error-handler path funnels through one builder, and -it also rewrites ``e.data`` because flask-restx ``Api.handle_error`` lets a -pre-existing ``e.data`` override the registered handler's return value. +mandated by the OAuth spec):: + + code str semantic error code (OpenApiErrorCode member) + message str human-readable summary + status int HTTP status, duplicated in the body + hint str | None actionable next step for the caller + details list[ErrorDetail] per-field validation breakdown {type, loc, msg} + +``OpenApiErrorFormatter`` is injected into ``ExternalApi`` so every +error-handler path funnels through one builder, and it also rewrites +``e.data`` because flask-restx ``Api.handle_error`` lets a pre-existing +``e.data`` override the registered handler's return value. """ from enum import StrEnum