Skip to content

docs(api): daily audit 2026-08-25 — align stale envelope schemas (safari + consolidated)#310

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ysyneu merged 1 commit into from
Aug 25, 2026
Merged

docs(api): daily audit 2026-08-25 — align stale envelope schemas (safari + consolidated) #310

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 27 additions & 3 deletions api-reference/openapi.en.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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",
Expand All@@ -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",
Expand All@@ -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": [
Expand Down
34 changes: 29 additions & 5 deletions api-reference/openapi.zh.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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",
Expand All@@ -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": [
Expand DownExpand Up@@ -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",
Expand Down
30 changes: 27 additions & 3 deletions api-reference/safari.openapi.en.json
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -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": [
Expand DownExpand Up@@ -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",
Expand All@@ -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",
Expand Down
Loading
Loading