From 836c9febf78187afb210162669c47aad5e9a5ffb Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 24 Jun 2026 09:12:50 +0200 Subject: [PATCH] docs(API): add cause + remediation to shared error responses MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review feedback on the API-doc-quality PRs: error response descriptions should live in the shared responses.yaml so they stay consistent across endpoints, instead of being re-authored inline per operation (where they drifted, and where — under OpenAPI 3.0 — a description sibling of $ref is ignored and never renders). Enrich the shared 400/401/403/404/409/422/429 descriptions once with a concise, generic cause and remediation. The wording is platform-wide only: no operation-specific detail and no invented machine-readable error codes (the Strings error envelope is { message, errors: [{ resource, field, message }] }, which the 422 text reflects). Every operation now inherits this through its bare $ref. Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 14 +++++++------- responses.yaml | 35 ++++++++++++++++++++++++++++------- 2 files changed, 35 insertions(+), 14 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index c08034f8..5e8ad5c2 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5473,7 +5473,7 @@ } }, "400": { - "description": "Bad request", + "description": "Bad request. The request could not be parsed or a parameter failed validation. Verify the request body, the content type, and the parameter types, then retry.", "headers": { "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" @@ -5487,10 +5487,10 @@ } }, "401": { - "description": "Unauthorized" + "description": "Unauthorized. Authentication failed because the access token is missing, expired, or invalid. Supply a valid access token and retry." }, "403": { - "description": "Forbidden", + "description": "Forbidden. The credentials are valid but not permitted for this request: the access token may lack the required scope, the user may lack permission on the resource, or the account plan may not include the feature. Use a token with the required scope on an account and user that hold the necessary permissions.", "headers": { "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" @@ -5504,7 +5504,7 @@ } }, "404": { - "description": "Not Found", + "description": "Not found. The requested resource does not exist or is not visible to the authenticated user. Verify the identifiers in the request path and that the token has access to them, then retry.", "headers": { "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" @@ -5518,7 +5518,7 @@ } }, "409": { - "description": "Conflict", + "description": "Conflict. The request conflicts with the current state of the resource. Reconcile the conflicting state and retry.", "headers": { "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" @@ -5532,7 +5532,7 @@ } }, "422": { - "description": "Unprocessable entity", + "description": "Unprocessable entity. The request was well-formed but failed validation. The response body lists each offending field in the `errors` array, with its resource, field, and a human-readable message. Correct the listed fields and retry.", "content": { "application/json": { "schema": { @@ -5585,7 +5585,7 @@ } }, "429": { - "description": "Rate Limiting", + "description": "Too many requests. The rate limit has been exceeded. Wait until the time indicated by the `X-Rate-Limit-Reset` response header before retrying.", "headers": { "X-Rate-Limit-Limit": { "$ref": "#/components/headers/X-Rate-Limit-Limit" diff --git a/responses.yaml b/responses.yaml index 1f98556f..3cf3a3dc 100644 --- a/responses.yaml +++ b/responses.yaml @@ -35,7 +35,10 @@ X-Rate-Limit-Reset: $ref: "./headers.yaml#/X-Rate-Limit-Reset" 400: - description: Bad request + description: >- + Bad request. The request could not be parsed or a parameter failed + validation. Verify the request body, the content type, and the parameter + types, then retry. headers: X-Rate-Limit-Limit: $ref: "./headers.yaml#/X-Rate-Limit-Limit" @@ -44,9 +47,16 @@ X-Rate-Limit-Reset: $ref: "./headers.yaml#/X-Rate-Limit-Reset" 401: - description: Unauthorized + description: >- + Unauthorized. Authentication failed because the access token is missing, + expired, or invalid. Supply a valid access token and retry. 403: - description: Forbidden + description: >- + Forbidden. The credentials are valid but not permitted for this request: + the access token may lack the required scope, the user may lack permission + on the resource, or the account plan may not include the feature. Use a + token with the required scope on an account and user that hold the + necessary permissions. headers: X-Rate-Limit-Limit: $ref: "./headers.yaml#/X-Rate-Limit-Limit" @@ -55,7 +65,10 @@ X-Rate-Limit-Reset: $ref: "./headers.yaml#/X-Rate-Limit-Reset" 404: - description: Not Found + description: >- + Not found. The requested resource does not exist or is not visible to the + authenticated user. Verify the identifiers in the request path and that the + token has access to them, then retry. headers: X-Rate-Limit-Limit: $ref: "./headers.yaml#/X-Rate-Limit-Limit" @@ -64,7 +77,9 @@ X-Rate-Limit-Reset: $ref: "./headers.yaml#/X-Rate-Limit-Reset" 409: - description: Conflict + description: >- + Conflict. The request conflicts with the current state of the resource. + Reconcile the conflicting state and retry. headers: X-Rate-Limit-Limit: $ref: "./headers.yaml#/X-Rate-Limit-Limit" @@ -73,7 +88,11 @@ X-Rate-Limit-Reset: $ref: "./headers.yaml#/X-Rate-Limit-Reset" 422: - description: Unprocessable entity + description: >- + Unprocessable entity. The request was well-formed but failed validation. + The response body lists each offending field in the `errors` array, with + its resource, field, and a human-readable message. Correct the listed + fields and retry. content: application/json: schema: @@ -86,7 +105,9 @@ X-Rate-Limit-Reset: $ref: "./headers.yaml#/X-Rate-Limit-Reset" 429: - description: Rate Limiting + description: >- + Too many requests. The rate limit has been exceeded. Wait until the time + indicated by the `X-Rate-Limit-Reset` response header before retrying. headers: X-Rate-Limit-Limit: $ref: "./headers.yaml#/X-Rate-Limit-Limit"