From 0e46124348abd7e356664000eaa4908c5f9a4043 Mon Sep 17 00:00:00 2001 From: Flashduty AI-SRE Date: Tue, 25 Aug 2026 08:10:59 +0000 Subject: [PATCH] =?UTF-8?q?docs(api):=20daily=20audit=202026-08-25=20?= =?UTF-8?q?=E2=80=94=20align=20stale=20envelope=20schemas=20in=20safari=20?= =?UTF-8?q?+=20consolidated?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- api-reference/openapi.en.json | 30 +++++++++++++++++++++--- api-reference/openapi.zh.json | 34 ++++++++++++++++++++++++---- api-reference/safari.openapi.en.json | 30 +++++++++++++++++++++--- api-reference/safari.openapi.zh.json | 34 ++++++++++++++++++++++++---- 4 files changed, 112 insertions(+), 16 deletions(-) diff --git a/api-reference/openapi.en.json b/api-reference/openapi.en.json index 4edc9eb..3b08147 100644 --- a/api-reference/openapi.en.json +++ b/api-reference/openapi.en.json @@ -31173,7 +31173,7 @@ }, "ErrorCode": { "type": "string", - "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", + "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |", "enum": [ "OK", "InvalidParameter", @@ -31195,7 +31195,30 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ] + ], + "x-enumDescriptions": { + "OK": "Reserved — not returned on real errors.", + "InvalidParameter": "A required parameter is missing or failed validation.", + "BadRequest": "Generic 400 used when no more specific code fits.", + "InvalidContentType": "The `Content-Type` header is not `application/json`.", + "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).", + "NoLicense": "The feature is license-gated and no active license was found.", + "ReferenceExist": "Deletion blocked — other entities still reference this resource.", + "Unauthorized": "`app_key` is missing, invalid, or expired.", + "BalanceNotEnough": "Billing-gated operation with insufficient account balance.", + "AccessDenied": "Authenticated but lacking the permission required for this operation.", + "RouteNotFound": "The request URL path is not a known route.", + "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.", + "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.", + "RequestLocked": "Operation temporarily locked due to repeated failures.", + "EntityTooLarge": "Request body exceeds the configured max size.", + "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.", + "RequestVerifyRequired": "Second-factor verification required but not supplied.", + "DangerousOperation": "High-risk operation requires MFA verification.", + "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.", + "ServiceUnavailable": "A backend dependency is unavailable. Try again later." + }, + "example": "InvalidParameter" }, "DutyError": { "type": "object", @@ -31206,7 +31229,8 @@ }, "message": { "type": "string", - "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." + "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.", + "example": "The specified parameter template_id is not valid." } }, "required": [ diff --git a/api-reference/openapi.zh.json b/api-reference/openapi.zh.json index 3948a5e..b01a2df 100644 --- a/api-reference/openapi.zh.json +++ b/api-reference/openapi.zh.json @@ -31165,7 +31165,7 @@ }, "ErrorCode": { "type": "string", - "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", + "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |", "enum": [ "OK", "InvalidParameter", @@ -31187,18 +31187,42 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ] + ], + "x-enumDescriptions": { + "OK": "保留值，正常错误响应不会返回。", + "InvalidParameter": "必填参数缺失或未通过校验。", + "BadRequest": "通用的 400 错误，通常是请求本身不合法。", + "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。", + "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。", + "NoLicense": "功能需要有效授权，但未找到可用的 license。", + "ReferenceExist": "该资源仍被其他实体引用，无法删除。", + "Unauthorized": "`app_key` 缺失、无效或已过期。", + "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。", + "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。", + "RouteNotFound": "请求的 URL 路径不是已知路由。", + "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。", + "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。", + "RequestLocked": "因连续失败被临时锁定。", + "EntityTooLarge": "请求体超过允许的最大长度。", + "RequestTooFrequently": "命中限流（全局、账户级或集成级）。", + "RequestVerifyRequired": "操作需要二次验证码，但未提供。", + "DangerousOperation": "危险操作，需要进行 MFA 验证。", + "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。", + "ServiceUnavailable": "后端依赖不可用，请稍后重试。" + }, + "example": "InvalidParameter" }, "DutyError": { "type": "object", - "description": "Error payload inside the response envelope. Present only on non-2xx responses.", + "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", - "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." + "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", + "example": "The specified parameter template_id is not valid." } }, "required": [ @@ -31226,7 +31250,7 @@ }, "ErrorResponse": { "type": "object", - "description": "Response envelope for errors. `error` is required; `data` is absent.", + "description": "错误响应结构。`error` 必填，`data` 不存在。", "properties": { "request_id": { "type": "string", diff --git a/api-reference/safari.openapi.en.json b/api-reference/safari.openapi.en.json index 2f3fbec..e59ed41 100644 --- a/api-reference/safari.openapi.en.json +++ b/api-reference/safari.openapi.en.json @@ -5392,7 +5392,8 @@ }, "message": { "type": "string", - "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." + "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request.", + "example": "The specified parameter template_id is not valid." } }, "required": [ @@ -5441,7 +5442,7 @@ }, "ErrorCode": { "type": "string", - "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", + "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these stable wire strings. HTTP status is informational — the authoritative signal is the enum value.\n\n| Code | HTTP | Meaning |\n|---|---|---|\n| `OK` | 200 | Reserved — not returned on real errors. |\n| `InvalidParameter` | 400 | A required parameter is missing or failed validation. |\n| `BadRequest` | 400 | Generic 400 used when no more specific code fits. |\n| `InvalidContentType` | 400 | The `Content-Type` header is not `application/json`. |\n| `ResourceNotFound` | 400 | The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice). |\n| `NoLicense` | 400 | The feature is license-gated and no active license was found. |\n| `ReferenceExist` | 400 | Deletion blocked — other entities still reference this resource. |\n| `Unauthorized` | 401 | `app_key` is missing, invalid, or expired. |\n| `BalanceNotEnough` | 402 | Billing-gated operation with insufficient account balance. |\n| `AccessDenied` | 403 | Authenticated but lacking the permission required for this operation. |\n| `RouteNotFound` | 404 | The request URL path is not a known route. |\n| `MethodNotAllowed` | 405 | The HTTP method is not allowed on this otherwise-known path. |\n| `UndonedOrderExist` | 409 | An outstanding billing order blocks this new one. Wait and retry. |\n| `RequestLocked` | 423 | Operation temporarily locked due to repeated failures. |\n| `EntityTooLarge` | 413 | Request body exceeds the configured max size. |\n| `RequestTooFrequently` | 429 | Rate limit hit — API-global, per-account, or per-integration. |\n| `RequestVerifyRequired` | 428 | Second-factor verification required but not supplied. |\n| `DangerousOperation` | 428 | High-risk operation requires MFA verification. |\n| `InternalError` | 500 | Unhandled server-side error. Include `request_id` in the bug report. |\n| `ServiceUnavailable` | 503 | A backend dependency is unavailable. Try again later. |", "enum": [ "OK", "InvalidParameter", @@ -5463,7 +5464,30 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ] + ], + "x-enumDescriptions": { + "OK": "Reserved — not returned on real errors.", + "InvalidParameter": "A required parameter is missing or failed validation.", + "BadRequest": "Generic 400 used when no more specific code fits.", + "InvalidContentType": "The `Content-Type` header is not `application/json`.", + "ResourceNotFound": "The referenced resource does not exist. Note: returned as HTTP 400, not 404 (historical choice).", + "NoLicense": "The feature is license-gated and no active license was found.", + "ReferenceExist": "Deletion blocked — other entities still reference this resource.", + "Unauthorized": "`app_key` is missing, invalid, or expired.", + "BalanceNotEnough": "Billing-gated operation with insufficient account balance.", + "AccessDenied": "Authenticated but lacking the permission required for this operation.", + "RouteNotFound": "The request URL path is not a known route.", + "MethodNotAllowed": "The HTTP method is not allowed on this otherwise-known path.", + "UndonedOrderExist": "An outstanding billing order blocks this new one. Wait and retry.", + "RequestLocked": "Operation temporarily locked due to repeated failures.", + "EntityTooLarge": "Request body exceeds the configured max size.", + "RequestTooFrequently": "Rate limit hit — API-global, per-account, or per-integration.", + "RequestVerifyRequired": "Second-factor verification required but not supplied.", + "DangerousOperation": "High-risk operation requires MFA verification.", + "InternalError": "Unhandled server-side error. Include `request_id` in the bug report.", + "ServiceUnavailable": "A backend dependency is unavailable. Try again later." + }, + "example": "InvalidParameter" }, "ErrorResponse": { "type": "object", diff --git a/api-reference/safari.openapi.zh.json b/api-reference/safari.openapi.zh.json index 97bb57d..cd2538e 100644 --- a/api-reference/safari.openapi.zh.json +++ b/api-reference/safari.openapi.zh.json @@ -5385,14 +5385,15 @@ }, "DutyError": { "type": "object", - "description": "Error payload inside the response envelope. Present only on non-2xx responses.", + "description": "响应结构中的错误 payload，仅在非 2xx 响应时出现。", "properties": { "code": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", - "description": "Human-readable error message, localized by the caller's Accept-Language. May contain field names, IDs, or other context from the failing request." + "description": "用户可读的错误描述，语言会跟随调用方的 Accept-Language。可能包含字段名、ID 等请求上下文。", + "example": "The specified parameter template_id is not valid." } }, "required": [ @@ -5441,7 +5442,7 @@ }, "ErrorCode": { "type": "string", - "description": "Flashduty error code enum. Every failed API response sets `error.code` to one of these values. The value is a stable wire string — not a localized message and not a numeric status. HTTP status is informational.", + "description": "Flashduty 错误码枚举。每个失败响应的 `error.code` 都是下列稳定值之一，HTTP 状态码仅作参考。\n\n| 错误码 | HTTP | 含义 |\n|---|---|---|\n| `OK` | 200 | 保留值，正常错误响应不会返回。 |\n| `InvalidParameter` | 400 | 必填参数缺失或未通过校验。 |\n| `BadRequest` | 400 | 通用的 400 错误，通常是请求本身不合法。 |\n| `InvalidContentType` | 400 | 请求头 `Content-Type` 不是 `application/json`。 |\n| `ResourceNotFound` | 400 | 目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。 |\n| `NoLicense` | 400 | 功能需要有效授权，但未找到可用的 license。 |\n| `ReferenceExist` | 400 | 该资源仍被其他实体引用，无法删除。 |\n| `Unauthorized` | 401 | `app_key` 缺失、无效或已过期。 |\n| `BalanceNotEnough` | 402 | 账户余额不足，无法执行需要计费的操作。 |\n| `AccessDenied` | 403 | 身份认证通过，但 RBAC 权限不足以执行该操作。 |\n| `RouteNotFound` | 404 | 请求的 URL 路径不是已知路由。 |\n| `MethodNotAllowed` | 405 | 当前路径不接受所使用的 HTTP 方法。 |\n| `UndonedOrderExist` | 409 | 账户存在未完成的订单，请稍后重试。 |\n| `RequestLocked` | 423 | 因连续失败被临时锁定。 |\n| `EntityTooLarge` | 413 | 请求体超过允许的最大长度。 |\n| `RequestTooFrequently` | 429 | 命中限流（全局、账户级或集成级）。 |\n| `RequestVerifyRequired` | 428 | 操作需要二次验证码，但未提供。 |\n| `DangerousOperation` | 428 | 危险操作，需要进行 MFA 验证。 |\n| `InternalError` | 500 | 服务端未预期错误。反馈问题请附上 `request_id`。 |\n| `ServiceUnavailable` | 503 | 后端依赖不可用，请稍后重试。 |", "enum": [ "OK", "InvalidParameter", @@ -5463,11 +5464,34 @@ "DangerousOperation", "InternalError", "ServiceUnavailable" - ] + ], + "x-enumDescriptions": { + "OK": "保留值，正常错误响应不会返回。", + "InvalidParameter": "必填参数缺失或未通过校验。", + "BadRequest": "通用的 400 错误，通常是请求本身不合法。", + "InvalidContentType": "请求头 `Content-Type` 不是 `application/json`。", + "ResourceNotFound": "目标资源不存在。注意 HTTP 状态码是 400 而非 404（历史设计）。", + "NoLicense": "功能需要有效授权，但未找到可用的 license。", + "ReferenceExist": "该资源仍被其他实体引用，无法删除。", + "Unauthorized": "`app_key` 缺失、无效或已过期。", + "BalanceNotEnough": "账户余额不足，无法执行需要计费的操作。", + "AccessDenied": "身份认证通过，但 RBAC 权限不足以执行该操作。", + "RouteNotFound": "请求的 URL 路径不是已知路由。", + "MethodNotAllowed": "当前路径不接受所使用的 HTTP 方法。", + "UndonedOrderExist": "账户存在未完成的订单，请稍后重试。", + "RequestLocked": "因连续失败被临时锁定。", + "EntityTooLarge": "请求体超过允许的最大长度。", + "RequestTooFrequently": "命中限流（全局、账户级或集成级）。", + "RequestVerifyRequired": "操作需要二次验证码，但未提供。", + "DangerousOperation": "危险操作，需要进行 MFA 验证。", + "InternalError": "服务端未预期错误。反馈问题请附上 `request_id`。", + "ServiceUnavailable": "后端依赖不可用，请稍后重试。" + }, + "example": "InvalidParameter" }, "ErrorResponse": { "type": "object", - "description": "Response envelope for errors. `error` is required; `data` is absent.", + "description": "错误响应结构。`error` 必填，`data` 不存在。", "properties": { "request_id": { "type": "string",