{
  "openapi": "3.1.0",
  "info": {
    "title": "MailDock 邮箱接码 API",
    "version": "1.0.0",
    "description": "面向第三方服务端的邮箱接码 API。所有 /v1 接口需要 Bearer API Key。金额和验证码使用字符串；下单异步、余额先冻结。示例 UUID、邮箱与验证码均为虚构。"
  },
  "servers": [
    {
      "url": "https://mail.jqiudata.com"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "tags": [
    {
      "name": "商品"
    },
    {
      "name": "订单"
    },
    {
      "name": "钱包"
    }
  ],
  "externalDocs": {
    "description": "第三方接入指南",
    "url": "https://mail.jqiudata.com/docs/"
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "在工作台 /keys/ 创建的客户 API Key；服务端保存。"
      }
    },
    "schemas": {
      "Product": {
        "type": "object",
        "required": [
          "id",
          "service",
          "name",
          "domain",
          "price",
          "unit",
          "stock",
          "quoted_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "商品 UUID；申请邮箱时传 product_id。",
            "format": "uuid"
          },
          "service": {
            "type": "string",
            "description": "服务标识，仅供展示与搜索；下单使用商品 UUID。"
          },
          "name": {
            "type": "string",
            "description": "目标服务名称。"
          },
          "domain": {
            "type": "string",
            "description": "邮箱类型。"
          },
          "price": {
            "type": "string",
            "description": "当前每次接码的客户售价；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          },
          "unit": {
            "type": "string",
            "description": "钱包计价单位，以响应为准。"
          },
          "stock": {
            "type": "integer",
            "minimum": 0,
            "description": "最近同步库存，不是下单保证。"
          },
          "quoted_at": {
            "type": "string",
            "description": "最近报价时间，带时区的 ISO 8601 字符串。",
            "format": "date-time"
          }
        },
        "example": {
          "id": "87c21967-8aa9-4496-9913-fb24b7a77691",
          "service": "ka",
          "name": "Shopee",
          "domain": "gmail.com",
          "price": "0.216",
          "unit": "余额点",
          "stock": 100,
          "quoted_at": "2026-11-14T10:00:00+00:00"
        }
      },
      "Balance": {
        "type": "object",
        "required": [
          "available",
          "frozen",
          "unit"
        ],
        "properties": {
          "available": {
            "type": "string",
            "description": "可用余额；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          },
          "frozen": {
            "type": "string",
            "description": "订单冻结余额；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          },
          "unit": {
            "type": "string",
            "description": "计价单位；不要自行当作人民币或美元。"
          }
        },
        "example": {
          "available": "10",
          "frozen": "0",
          "unit": "余额点"
        }
      },
      "Order": {
        "type": "object",
        "required": [
          "id",
          "service",
          "service_name",
          "domain",
          "email",
          "state",
          "state_label",
          "price",
          "unit",
          "settlement",
          "code",
          "created_at",
          "expires_at",
          "received_at"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "订单 UUID，后续查询和取消使用此值。",
            "format": "uuid"
          },
          "service": {
            "type": "string",
            "description": "订单锁定的服务标识。"
          },
          "service_name": {
            "type": "string",
            "description": "服务名称。"
          },
          "domain": {
            "type": "string",
            "description": "邮箱类型。"
          },
          "email": {
            "type": [
              "string",
              "null"
            ],
            "description": "分配前为空；示例地址不是可用邮箱。",
            "format": "email"
          },
          "state": {
            "type": "string",
            "description": "订单处理状态。",
            "enum": [
              "creating",
              "waiting",
              "received",
              "completed",
              "cancel_requested",
              "canceled",
              "failed",
              "review"
            ]
          },
          "state_label": {
            "type": "string",
            "description": "状态中文文案；程序判断请使用 state。"
          },
          "price": {
            "type": "string",
            "description": "创建时锁定的实际售价；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          },
          "unit": {
            "type": "string",
            "description": "订单计价单位。"
          },
          "settlement": {
            "type": "string",
            "description": "资金状态，与处理状态分别判断。",
            "enum": [
              "reserved",
              "captured",
              "released",
              "refunded"
            ]
          },
          "code": {
            "type": [
              "string",
              "null"
            ],
            "description": "尚未收到为空；可包含前导零、字母，不限定六位。有值即已交付，即使 state 为 review。"
          },
          "created_at": {
            "type": "string",
            "description": "订单创建时间。",
            "format": "date-time"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "分配后返回的预计等待截止时间；到期不等于即时退款。",
            "format": "date-time"
          },
          "received_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "验证码交付时间。",
            "format": "date-time"
          }
        },
        "example": {
          "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
          "service": "ka",
          "service_name": "Shopee",
          "domain": "gmail.com",
          "email": "sample@example.com",
          "state": "received",
          "state_label": "验证码已送达",
          "price": "0.216",
          "unit": "余额点",
          "settlement": "captured",
          "code": "001234",
          "created_at": "2026-11-14T10:00:10+00:00",
          "expires_at": "2026-11-14T10:10:15+00:00",
          "received_at": "2026-11-14T10:01:00+00:00"
        }
      },
      "CreateOrder": {
        "type": "object",
        "required": [
          "product_id",
          "max_price"
        ],
        "properties": {
          "product_id": {
            "type": "string",
            "description": "从商品目录取得的 UUID。",
            "format": "uuid"
          },
          "max_price": {
            "type": "string",
            "description": "客户允许的最高售价，必须大于 0 且不超过 1000000000；建议使用刚查询的 price；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          }
        },
        "example": {
          "product_id": "87c21967-8aa9-4496-9913-fb24b7a77691",
          "max_price": "0.216"
        }
      },
      "OrderResult": {
        "type": "object",
        "required": [
          "order"
        ],
        "properties": {
          "order": {
            "$ref": "#/components/schemas/Order"
          }
        },
        "example": {
          "order": {
            "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
            "service": "ka",
            "service_name": "Shopee",
            "domain": "gmail.com",
            "email": "sample@example.com",
            "state": "received",
            "state_label": "验证码已送达",
            "price": "0.216",
            "unit": "余额点",
            "settlement": "captured",
            "code": "001234",
            "created_at": "2026-11-14T10:00:10+00:00",
            "expires_at": "2026-11-14T10:10:15+00:00",
            "received_at": "2026-11-14T10:01:00+00:00"
          }
        }
      },
      "CreateOrderResult": {
        "type": "object",
        "required": [
          "order",
          "created"
        ],
        "properties": {
          "order": {
            "$ref": "#/components/schemas/Order"
          },
          "created": {
            "type": "boolean",
            "description": "true 为新建，false 为同一幂等请求的既有订单。"
          }
        },
        "example": {
          "order": {
            "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
            "service": "ka",
            "service_name": "Shopee",
            "domain": "gmail.com",
            "email": null,
            "state": "creating",
            "state_label": "正在分配",
            "price": "0.216",
            "unit": "余额点",
            "settlement": "reserved",
            "code": null,
            "created_at": "2026-11-14T10:00:10+00:00",
            "expires_at": null,
            "received_at": null
          },
          "created": true
        }
      },
      "Transaction": {
        "type": "object",
        "required": [
          "id",
          "kind",
          "amount",
          "available_delta",
          "frozen_delta",
          "available_after",
          "frozen_after",
          "note",
          "created_at"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "minimum": 1,
            "description": "账本流水 ID。"
          },
          "kind": {
            "type": "string",
            "description": "流水类型。",
            "enum": [
              "reserve",
              "release",
              "capture",
              "topup",
              "refund"
            ]
          },
          "amount": {
            "type": "string",
            "description": "本次事件的有符号金额；不可将所有事件直接相加当消费金额；十进制字符串，最多 8 位小数。",
            "pattern": "^-?\\d+(\\.\\d{1,8})?$"
          },
          "available_delta": {
            "type": "string",
            "description": "可用余额变化量；十进制字符串，最多 8 位小数。",
            "pattern": "^-?\\d+(\\.\\d{1,8})?$"
          },
          "frozen_delta": {
            "type": "string",
            "description": "冻结余额变化量；十进制字符串，最多 8 位小数。",
            "pattern": "^-?\\d+(\\.\\d{1,8})?$"
          },
          "available_after": {
            "type": "string",
            "description": "事件后的可用余额；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          },
          "frozen_after": {
            "type": "string",
            "description": "事件后的冻结余额；十进制字符串，最多 8 位小数。",
            "pattern": "^\\d+(\\.\\d{1,8})?$"
          },
          "note": {
            "type": "string",
            "description": "流水说明。"
          },
          "created_at": {
            "type": "string",
            "description": "发生时间。",
            "format": "date-time"
          }
        },
        "example": {
          "id": 1001,
          "kind": "reserve",
          "amount": "-0.216",
          "available_delta": "-0.216",
          "frozen_delta": "0.216",
          "available_after": "9.784",
          "frozen_after": "0.216",
          "note": "订单余额冻结",
          "created_at": "2026-11-14T10:00:10+00:00"
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "properties": {
              "code": {
                "type": "string",
                "description": "稳定错误码，请按 code 分支处理。"
              },
              "message": {
                "type": "string",
                "description": "可读错误说明。"
              }
            }
          }
        },
        "example": {
          "error": {
            "code": "insufficient_balance",
            "message": "余额不足，请先充值。"
          }
        }
      },
      "ProductList": {
        "type": "object",
        "required": [
          "items",
          "page",
          "page_size",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "page_size": {
            "type": "integer",
            "const": 50
          },
          "total": {
            "type": "integer",
            "minimum": 0
          }
        },
        "example": {
          "items": [
            {
              "id": "87c21967-8aa9-4496-9913-fb24b7a77691",
              "service": "ka",
              "name": "Shopee",
              "domain": "gmail.com",
              "price": "0.216",
              "unit": "余额点",
              "stock": 100,
              "quoted_at": "2026-11-14T10:00:00+00:00"
            }
          ],
          "page": 1,
          "page_size": 50,
          "total": 1
        }
      },
      "OrderList": {
        "type": "object",
        "required": [
          "items",
          "page",
          "page_size",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Order"
            }
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "page_size": {
            "type": "integer",
            "const": 50
          },
          "total": {
            "type": "integer",
            "minimum": 0
          }
        },
        "example": {
          "items": [
            {
              "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
              "service": "ka",
              "service_name": "Shopee",
              "domain": "gmail.com",
              "email": "sample@example.com",
              "state": "received",
              "state_label": "验证码已送达",
              "price": "0.216",
              "unit": "余额点",
              "settlement": "captured",
              "code": "001234",
              "created_at": "2026-11-14T10:00:10+00:00",
              "expires_at": "2026-11-14T10:10:15+00:00",
              "received_at": "2026-11-14T10:01:00+00:00"
            }
          ],
          "page": 1,
          "page_size": 50,
          "total": 1
        }
      },
      "TransactionList": {
        "type": "object",
        "required": [
          "items",
          "page",
          "page_size",
          "total"
        ],
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Transaction"
            }
          },
          "page": {
            "type": "integer",
            "minimum": 1,
            "maximum": 100000
          },
          "page_size": {
            "type": "integer",
            "const": 50
          },
          "total": {
            "type": "integer",
            "minimum": 0
          }
        },
        "example": {
          "items": [
            {
              "id": 1001,
              "kind": "reserve",
              "amount": "-0.216",
              "available_delta": "-0.216",
              "frozen_delta": "0.216",
              "available_after": "9.784",
              "frozen_after": "0.216",
              "note": "订单余额冻结",
              "created_at": "2026-11-14T10:00:10+00:00"
            }
          ],
          "page": 1,
          "page_size": 50,
          "total": 1
        }
      }
    }
  },
  "paths": {
    "/v1/products": {
      "get": {
        "operationId": "products",
        "summary": "查询可售商品",
        "description": "仅返回已上架且最近库存大于零的商品；按名称、邮箱类型排序。报价通常每 2 分钟刷新，超过 5 分钟会阻止新下单。库存与报价可能在下单前变化。",
        "tags": [
          "商品"
        ],
        "parameters": [
          {
            "name": "search",
            "in": "query",
            "description": "服务名称或标识的包含匹配，忽略大小写，最多使用前 100 字。",
            "schema": {
              "type": "string",
              "maxLength": 100
            }
          },
          {
            "name": "domain",
            "in": "query",
            "description": "邮箱类型精确匹配，从目录返回值中选择。",
            "schema": {
              "type": "string",
              "maxLength": 160
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "每页固定 50 项。默认 1；数值越界会限定到 1–100000；非整数返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductList"
                },
                "example": {
                  "items": [
                    {
                      "id": "87c21967-8aa9-4496-9913-fb24b7a77691",
                      "service": "ka",
                      "name": "Shopee",
                      "domain": "gmail.com",
                      "price": "0.216",
                      "unit": "余额点",
                      "stock": 100,
                      "quoted_at": "2026-11-14T10:00:00+00:00"
                    }
                  ],
                  "page": 1,
                  "page_size": 50,
                  "total": 1
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        }
      }
    },
    "/v1/balance": {
      "get": {
        "operationId": "balance",
        "summary": "查询钱包余额",
        "description": "网页与 API 共用账户余额。先冻结实际售价，验证码交付时扣费，确认未交付才释放冻结。",
        "tags": [
          "钱包"
        ],
        "parameters": [],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Balance"
                },
                "example": {
                  "available": "10",
                  "frozen": "0",
                  "unit": "余额点"
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        }
      }
    },
    "/v1/mail-orders": {
      "post": {
        "operationId": "create_order",
        "summary": "申请邮箱",
        "description": "202 仅表示订单已创建且余额已冻结，不代表邮箱已分配。用返回的订单 ID 轮询。200 表示相同幂等请求返回既有订单。max_price 是售价上限，实际冻结 order.price。",
        "tags": [
          "订单"
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "description": "8–100 个 ASCII 字符。同一账户按键去重。首次发送前持久化；超时重试沿用相同键和参数。建议 UUID。",
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 100
            },
            "example": "maildock-order-20261114-0001"
          }
        ],
        "responses": {
          "202": {
            "description": "已创建，等待异步分配邮箱",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrderResult"
                },
                "example": {
                  "order": {
                    "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
                    "service": "ka",
                    "service_name": "Shopee",
                    "domain": "gmail.com",
                    "email": null,
                    "state": "creating",
                    "state_label": "正在分配",
                    "price": "0.216",
                    "unit": "余额点",
                    "settlement": "reserved",
                    "code": null,
                    "created_at": "2026-11-14T10:00:10+00:00",
                    "expires_at": null,
                    "received_at": null
                  },
                  "created": true
                }
              }
            }
          },
          "200": {
            "description": "同一幂等请求的既有订单",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateOrderResult"
                },
                "example": {
                  "order": {
                    "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
                    "service": "ka",
                    "service_name": "Shopee",
                    "domain": "gmail.com",
                    "email": null,
                    "state": "creating",
                    "state_label": "正在分配",
                    "price": "0.216",
                    "unit": "余额点",
                    "settlement": "reserved",
                    "code": null,
                    "created_at": "2026-11-14T10:00:10+00:00",
                    "expires_at": null,
                    "received_at": null
                  },
                  "created": false
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "409": {
            "description": "insufficient_balance / unavailable_product / stale_quote / price_changed / idempotency_conflict / already_delivered / under_review / conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_balance": {
                    "value": {
                      "error": {
                        "code": "insufficient_balance",
                        "message": "可用余额不足。"
                      }
                    }
                  },
                  "unavailable_product": {
                    "value": {
                      "error": {
                        "code": "unavailable_product",
                        "message": "商品无库存、已下架或不存在。"
                      }
                    }
                  },
                  "stale_quote": {
                    "value": {
                      "error": {
                        "code": "stale_quote",
                        "message": "商品报价超过有效时间。"
                      }
                    }
                  },
                  "price_changed": {
                    "value": {
                      "error": {
                        "code": "price_changed",
                        "message": "当前售价高于 max_price。"
                      }
                    }
                  },
                  "idempotency_conflict": {
                    "value": {
                      "error": {
                        "code": "idempotency_conflict",
                        "message": "同一键绑定的商品或价格参数不同。"
                      }
                    }
                  },
                  "already_delivered": {
                    "value": {
                      "error": {
                        "code": "already_delivered",
                        "message": "验证码已交付，不能取消。"
                      }
                    }
                  },
                  "under_review": {
                    "value": {
                      "error": {
                        "code": "under_review",
                        "message": "订单等待人工核对。"
                      }
                    }
                  },
                  "conflict": {
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "数据库操作冲突。"
                      }
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "ordering_paused / worker_unavailable",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "ordering_paused": {
                    "value": {
                      "error": {
                        "code": "ordering_paused",
                        "message": "平台暂停接单或尚未配置接单服务。"
                      }
                    }
                  },
                  "worker_unavailable": {
                    "value": {
                      "error": {
                        "code": "worker_unavailable",
                        "message": "后台收码任务暂不可用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrder"
              },
              "example": {
                "product_id": "87c21967-8aa9-4496-9913-fb24b7a77691",
                "max_price": "0.216"
              }
            }
          }
        }
      },
      "get": {
        "operationId": "orders",
        "summary": "查询订单列表",
        "description": "仅当前账户订单，按创建时间倒序。每项为完整 Order，含邮箱与验证码；多笔订单可合并轮询列表。不支持 state 过滤。",
        "tags": [
          "订单"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "每页固定 50 项。默认 1；数值越界会限定到 1–100000；非整数返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderList"
                },
                "example": {
                  "items": [
                    {
                      "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
                      "service": "ka",
                      "service_name": "Shopee",
                      "domain": "gmail.com",
                      "email": "sample@example.com",
                      "state": "received",
                      "state_label": "验证码已送达",
                      "price": "0.216",
                      "unit": "余额点",
                      "settlement": "captured",
                      "code": "001234",
                      "created_at": "2026-11-14T10:00:10+00:00",
                      "expires_at": "2026-11-14T10:10:15+00:00",
                      "received_at": "2026-11-14T10:01:00+00:00"
                    }
                  ],
                  "page": 1,
                  "page_size": 50,
                  "total": 1
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        }
      }
    },
    "/v1/mail-orders/{order_id}": {
      "get": {
        "operationId": "order_detail",
        "summary": "查询邮箱与验证码",
        "description": "邮箱尚未分配时 email 为 null；验证码尚未交付时 code 为 null。建议每 5 秒查询一次；先检查 code，再处理 state。",
        "tags": [
          "订单"
        ],
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "description": "属于当前账户的订单 UUID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResult"
                },
                "example": {
                  "order": {
                    "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
                    "service": "ka",
                    "service_name": "Shopee",
                    "domain": "gmail.com",
                    "email": "sample@example.com",
                    "state": "received",
                    "state_label": "验证码已送达",
                    "price": "0.216",
                    "unit": "余额点",
                    "settlement": "captured",
                    "code": "001234",
                    "created_at": "2026-11-14T10:00:10+00:00",
                    "expires_at": "2026-11-14T10:10:15+00:00",
                    "received_at": "2026-11-14T10:01:00+00:00"
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "记录不存在或不属于当前账户。"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        }
      }
    },
    "/v1/mail-orders/{order_id}/cancel": {
      "post": {
        "operationId": "cancel_order",
        "summary": "取消未交付订单",
        "description": "无需请求体。HTTP 200 可能返回 cancel_requested，须继续查询至 canceled/released。重复取消已取消、失败或取消中的订单返回当前订单；已交付或待核对返回 409。取消与收码并发时可能仍交付并扣费。",
        "tags": [
          "订单"
        ],
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "description": "属于当前账户的订单 UUID。",
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrderResult"
                },
                "example": {
                  "order": {
                    "id": "25d47c44-59dc-4c54-a04f-dc5fd5eef222",
                    "service": "ka",
                    "service_name": "Shopee",
                    "domain": "gmail.com",
                    "email": "sample@example.com",
                    "state": "cancel_requested",
                    "state_label": "取消处理中",
                    "price": "0.216",
                    "unit": "余额点",
                    "settlement": "reserved",
                    "code": null,
                    "created_at": "2026-11-14T10:00:10+00:00",
                    "expires_at": null,
                    "received_at": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "404": {
            "description": "not_found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "not_found": {
                    "value": {
                      "error": {
                        "code": "not_found",
                        "message": "记录不存在或不属于当前账户。"
                      }
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "insufficient_balance / unavailable_product / stale_quote / price_changed / idempotency_conflict / already_delivered / under_review / conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "insufficient_balance": {
                    "value": {
                      "error": {
                        "code": "insufficient_balance",
                        "message": "可用余额不足。"
                      }
                    }
                  },
                  "unavailable_product": {
                    "value": {
                      "error": {
                        "code": "unavailable_product",
                        "message": "商品无库存、已下架或不存在。"
                      }
                    }
                  },
                  "stale_quote": {
                    "value": {
                      "error": {
                        "code": "stale_quote",
                        "message": "商品报价超过有效时间。"
                      }
                    }
                  },
                  "price_changed": {
                    "value": {
                      "error": {
                        "code": "price_changed",
                        "message": "当前售价高于 max_price。"
                      }
                    }
                  },
                  "idempotency_conflict": {
                    "value": {
                      "error": {
                        "code": "idempotency_conflict",
                        "message": "同一键绑定的商品或价格参数不同。"
                      }
                    }
                  },
                  "already_delivered": {
                    "value": {
                      "error": {
                        "code": "already_delivered",
                        "message": "验证码已交付，不能取消。"
                      }
                    }
                  },
                  "under_review": {
                    "value": {
                      "error": {
                        "code": "under_review",
                        "message": "订单等待人工核对。"
                      }
                    }
                  },
                  "conflict": {
                    "value": {
                      "error": {
                        "code": "conflict",
                        "message": "数据库操作冲突。"
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        }
      }
    },
    "/v1/transactions": {
      "get": {
        "operationId": "transactions",
        "summary": "查询钱包流水",
        "description": "仅当前账户流水，按流水 ID 倒序。用 available_delta / frozen_delta 对账，不要把 reserve 与 capture 的 amount 重复计为消费。",
        "tags": [
          "钱包"
        ],
        "parameters": [
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "每页固定 50 项。默认 1；数值越界会限定到 1–100000；非整数返回 400。",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100000,
              "default": 1
            }
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TransactionList"
                },
                "example": {
                  "items": [
                    {
                      "id": 1001,
                      "kind": "reserve",
                      "amount": "-0.216",
                      "available_delta": "-0.216",
                      "frozen_delta": "0.216",
                      "available_after": "9.784",
                      "frozen_after": "0.216",
                      "note": "订单余额冻结",
                      "created_at": "2026-11-14T10:00:10+00:00"
                    }
                  ],
                  "page": 1,
                  "page_size": 50,
                  "total": 1
                }
              }
            }
          },
          "400": {
            "description": "invalid_json / invalid_request / invalid_amount / idempotency_required",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "invalid_json": {
                    "value": {
                      "error": {
                        "code": "invalid_json",
                        "message": "请求体不是合法 JSON 对象。"
                      }
                    }
                  },
                  "invalid_request": {
                    "value": {
                      "error": {
                        "code": "invalid_request",
                        "message": "字段缺失、类型错误或分页值无效。"
                      }
                    }
                  },
                  "invalid_amount": {
                    "value": {
                      "error": {
                        "code": "invalid_amount",
                        "message": "max_price 不在范围内或精度过高。"
                      }
                    }
                  },
                  "idempotency_required": {
                    "value": {
                      "error": {
                        "code": "idempotency_required",
                        "message": "幂等键缺失或格式不符。"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "authentication_required / invalid_auth / invalid_key",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "authentication_required": {
                    "value": {
                      "error": {
                        "code": "authentication_required",
                        "message": "未提供认证。"
                      }
                    }
                  },
                  "invalid_auth": {
                    "value": {
                      "error": {
                        "code": "invalid_auth",
                        "message": "Authorization 格式或认证方式不正确。"
                      }
                    }
                  },
                  "invalid_key": {
                    "value": {
                      "error": {
                        "code": "invalid_key",
                        "message": "密钥无效、已撤销或账户已停用。"
                      }
                    }
                  }
                }
              }
            }
          },
          "405": {
            "description": "method_not_allowed",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "method_not_allowed": {
                    "value": {
                      "error": {
                        "code": "method_not_allowed",
                        "message": "HTTP 方法不支持。"
                      }
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "rate_limited / too_many_orders",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "examples": {
                  "rate_limited": {
                    "value": {
                      "error": {
                        "code": "rate_limited",
                        "message": "同账户所有 Key 与网页 API 共用 120 次/分钟额度。"
                      }
                    }
                  },
                  "too_many_orders": {
                    "value": {
                      "error": {
                        "code": "too_many_orders",
                        "message": "已有 20 笔冻结订单（含待核对订单）。"
                      }
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "description": "建议等待秒数；当前固定 60。",
                "schema": {
                  "type": "integer",
                  "example": 60
                }
              }
            }
          },
          "default": {
            "description": "其他服务端、网关或路由错误可能不是 JSON。网络超时或 5xx 不能证明下单失败；保留幂等键和参数。"
          }
        }
      }
    }
  }
}