环境、限额与版本

沙箱与生产环境，共用一个基础 URL

基础 URL：https://api.dubaitrip.com/v1。沙箱与生产环境共用该地址；由签名所用的密钥选择环境。dt_sbx_ 密钥对接我们供应商的测试环境——搜索、定价、价格核验、下单、预订、出票和取消都能在测试库存上端到端运行，不产生真实机票或凭证，也不收取任何费用。dt_live_ 密钥在生产审核通过后签发，访问真实库存，并从您的保证金中结算。

沙箱与生产环境的预订在开发者门户中分开显示（每笔预订都有标注），权限范围、限额和 IP 规则也按环境分别管理。

速率限制与配额

每个密钥都受令牌桶（每秒持续请求数加突发量）和每日配额的限制。沙箱默认值：2 次请求/秒，突发量 5，2,000 次请求/天。生产环境限额按账户协商确定。超出令牌桶将返回 429 api_rate_limited 并附带 Retry-After 请求头；配额用尽将返回 429 api_quota_exceeded，直到 UTC 午夜。

繁重的搜索按设计采用异步方式：传入 wait=false 可立即获得 searchId 并轮询搜索端点，传入 wait=true 则在一次调用中获得完整结果。轮询与其他请求一样计入您的限额。

查订比限制

搜索次数还会根据您的预订数进行配给。滚动窗口期（默认 7 天）中的每一天都提供一定的免费搜索额度，而窗口期内每完成一笔预订，都会再增加 cap 次搜索——cap 即为您的账户约定的“每笔预订搜索次数”，显示在开发者门户中。轮询、定价、票价规则和内容读取从不计入；只有机票和酒店的搜索调用才计入。

额度用完后，搜索将返回 429 look_to_book_exceeded，并附带指向下一个 UTC 午夜的 Retry-After 请求头——届时窗口中最早的一天会被移出。一笔预订会立即重新释放额度。开发者门户中的“查订比”卡片显示实时计数、上限和剩余额度；如果您的集成确实需要远多于预订数的搜索，请联系我们提高上限，而不要在被拒绝后反复重试。

幂等性

涉及资金或库存的端点——创建订单或预订、出票、取消——都要求提供 Idempotency-Key 请求头（任意不超过 128 个字符的唯一字符串，UUID 最为理想）。使用相同的键重试将返回原始响应，而不会创建重复记录；在重复使用的键下发送不同的请求体将返回 409。

版本管理

版本号位于路径中（/v1）。新增型变更——新的可选字段、新的枚举值、新的端点——发布时不升级版本号，因此请以容错方式解析并忽略未知字段。破坏性变更会发布新的主版本，并提供迁移窗口期；“变更日志”指南列出了每一项变更。