跳到主要内容

PMS 连接错误

快速检查

大多数连接问题需要 5-10 分钟确认。 如果看到 429，请先等待重试时间再试。

当 AVA 无法连接、显示临时限流，或报告 PMS 拒绝时，请使用本指南。

自动重试

AVA 现在会自动重试某些短暂的 PMS 读取请求。 Opera OAuth 也会自动重试一次临时超时或网关错误。 办理入住期间，AVA 会在分配房间和最终办理入住时，重试临时预订冲突和 PMS 限流。 这些重试可能会让 AVA 在显示错误前多等待几秒。 你可能不会看到一次性网络错误。 Cloudbeds webhook 凭据失败不会自动重试。

保留 PMS 信息

如果 AVA 在刷新时显示具体的 PMS 错误，请使用该信息。 Streamliner 会保留原始 PMS 响应，而不是将其替换为通用技术错误。

常见错误信息​

错误含义处理方式
"Please fill all required PMS fields"所选 PMS 缺少必填字段填写该提供商显示的必填字段
"Failed to save PMS Integration"连接或身份验证错误重新检查 PMS 账号和权限
"Failed to save settings before connecting"OAuth 开始前另一个 Essentials 设置保存失败阅读完整信息，修复该设置，然后重新连接
"Unable to communicate with the property management system"网络或 API 问题刷新一次，然后再次测试连接
"429" 或 "rate limited"PMS 或 AVA 自身的请求预算要求稍后重试等待 AVA 重试入住操作，或按照显示的重试时间操作
"409" 或 "Conflict"PMS 因预订状态或请求不被允许而拒绝操作阅读 PMS 原因，修正预订，然后重试一次
PMS_RESERVATION_MUTATION_IN_PROGRESS短暂的 PMS 预订更新与房间分配或最终办理入住重叠短暂等待，刷新预订，然后只重试受影响的步骤一次
"502" 或 "Bad Gateway"Cloudbeds、Opera 或其他 PMS 在读取或写入期间失败阅读原因，刷新一次，然后重试操作
"503" 或 "Service Unavailable"PMS 或网络服务暂时无法完成请求检查 PMS 状态，刷新一次，然后重试操作
"non-reservations payload"eZee 返回了网站或其他响应，而不是预订数据检查 eZee Base URL；标准 API 应留空
"Unsupported Cloudbeds version"请求选择了已停用的 Cloudbeds v1 或 v2移除版本固定，然后开始新的连接
"You don't have access to property ID" 或 "success:false"Cloudbeds 阻止了该酒店，或返回逻辑访问失败确认 Cloudbeds 酒店正确，然后等待一分钟再试
"webhook credentials rejected"Cloudbeds 接受了登录，但拒绝了 webhook 设置重新连接 Cloudbeds，再次保存设置
"PMS cache unavailable" 或缓存失效错误AVA 无法确认各服务中的新 PMS 设置等待一分钟，然后再次保存；若重复出现，请联系支持
611 或 "Invalid Auth Code or Hotel Code"更改凭据后，eZee 拒绝了较旧的凭据快照保存匹配的 Hotel Code 和 Auth Code，然后重试一次
"reservationOverlapTo must be greater than reservationOverlapFrom"PMS 拒绝了住店重叠时间窗口在 PMS 中更新重叠值，然后刷新

临时连接故障​

你会看到： 一次性的连接错误、超时或空响应。

原因： AVA 会自动重试某些短暂的 PMS 读取请求。 它也会重试一次临时的 Opera OAuth 失败。 超时或网关错误在显示错误前可能需要最多 30 秒。 在 Opera 上，中断的客房清洁读取或写入可能显示为 502。

处理方法：

  1. 刷新页面一次。

  2. 再次尝试该操作。

  3. 如果持续失败，检查 PMS 连接。

  4. 如果同样的错误持续返回，请联系支持。

    ✓ 一次性故障通常无需更改设置就会消失。

PMS 请求耗时过长​

你会看到： PMS 操作等待一段时间后显示超时或连接错误。

原因： 对于没有更短限制的请求，AVA 会在等待 60 秒后停止等待。 某些预订和能力读取使用更短的限制。 这样可以防止一个缓慢的 PMS 响应让预订操作无限期保持打开。

处理方法：

  1. 等待超时信息出现。

  2. 再次尝试前刷新预订或页面。

  3. 重复写入操作前，先在 PMS 中检查预订。

  4. 只重试该操作一次。

  5. 如果超时再次出现，请联系支持。

    ✓ PMS 操作应在约一分钟内完成，或返回清晰的错误。

重试前先检查

结果不明确时，不要重复预订更新。 先在 PMS 中确认预订状态，然后只重试一次。

PMS 读取使用备用路径​

你会看到： PMS 读取耗时过长后，AVA 以较少的详细信息继续运行。

原因： 某些读取失败时会放行，以便住客或员工流程继续进行。 备用结果可能显示未补充详细信息的预订或更简单的搜索结果。 能力读取可能会暂时报告功能不可用。

你会看到的内容原因处理方式
预订详情不完整房型详情未能及时返回刷新预订后重试
员工搜索显示较少的住客详情个人资料搜索使用了预订姓名备用路径刷新页面后再次搜索
依赖日期的流程显示错误日期PMS 营业日期未能及时返回刷新，然后在 PMS 中确认营业日期
缺少 Group Checkout读取期间能力数据不可用刷新，然后检查 PMS 连接
支持的换房被拒绝AVA 无法确认所需能力刷新，然后只重试一次
重复写入前先检查 PMS

这些备用路径适用于读取。 如果写入超时，请先检查 PMS，再重试。

Opera 错误显示上游原因​

你会看到： Opera 操作显示 "Bad Gateway" 或 "Service Unavailable (503)"。

原因： Opera 或其网关返回了非 JSON 错误响应。 如果有可用的简短响应文本，AVA 会显示该文本；为空时则显示 HTTP 状态。

处理方法：

  1. 阅读完整错误信息并记下状态码。
  2. 如果正在添加共享住客，重试前检查 Opera。
  3. 对于其他操作，先刷新 AVA 一次，然后重试。
  4. 如果同样的错误再次出现，请检查 Opera 和 AVA。
  5. 如果错误持续，请联系支持。
重试前检查共享住客

AVA 会记录 Opera 共享住客创建进度。当所有住客都已办理入住且没有待处理的换房时，AVA 会返回结果，不再进行另一次 Opera 更新。 待处理的换房仍可进行协调。 短暂等待，刷新 AVA，并在重试前检查 Opera。 结果不明确时，不要手动创建另一个共享住客。

PMS 拒绝显示为冲突​

你会看到： 操作显示 409、"Conflict" 或具体的 PMS 拒绝信息。 它不再显示为通用服务器错误。

原因： PMS 因预订规则失败而拒绝了操作。 AVA 会保留上游状态和信息，以便你修正原因。 大多数 409 响应对该请求来说是永久性的。 PMS_RESERVATION_MUTATION_IN_PROGRESS 是房间分配或最终办理入住期间的临时例外。

处理方法：

  1. 阅读完整的 PMS 信息。

  2. 在 PMS 中打开预订。

  3. 修正信息指出的问题。

  4. 对于取消拒绝，检查住客是否已入住、应退房或已退房。

  5. 在 PMS 中完成必要的退房步骤，然后再重试在住取消。

  6. 刷新 AVA。

  7. 只重试该操作一次。

  8. 如果 PMS 仍然拒绝，请在 PMS 中完成该操作并联系支持。

    ✓ PMS 接受操作后，AVA 应显示更新后的预订状态。

预订更新仍在进行中​

你会看到： 房间分配或最终办理入住显示 PMS_RESERVATION_MUTATION_IN_PROGRESS。

原因： PMS 预订更新暂时占用了该预订。 住客验证、上传护照或其他预订更新后可能发生这种情况。 AVA 会在短时间内自动重试这一确切的冲突。

处理方法：

  1. 短暂等待 PMS 更新完成。

  2. 在 AVA 中刷新预订。

  3. 只重试受影响的步骤一次。

    ✓ 预订更新完成后，受影响的步骤应继续进行。

如果重试后代码仍然存在，请联系支持。 请附上预订编号、PMS 提供商和完整错误信息。

刷新期间出现 PMS 校验错误​

你会看到： 住店刷新期间出现 PMS 信息，例如 reservationOverlapTo must be greater than reservationOverlapFrom。

原因： PMS 因某项校验规则失败而拒绝了请求。

处理方法：

  1. 阅读准确的 PMS 信息。

  2. 在 PMS 中检查相关设置。

  3. 修正未通过校验的值。

  4. 刷新 AVA 一次。

    ✓ 只有在 PMS 数据修正前，你才会看到原始 PMS 信息。

连接失败​

你会看到： 点击 Connect 时出现错误信息。

先检查这些​

  1. 确认凭据正确

    • 仔细检查 API key 或 client credentials
    • 确认凭据前后没有多余空格
    • 确认凭据没有过期

  2. 确认 API 权限

    • 登录 PMS 管理门户
    • 确认你的账号已启用 API 访问
    • 检查是否已授予集成权限

  3. 检查网络连接

    • 尝试刷新页面
    • 测试 AVA 的其他部分以确认连接正常

尝试这样操作​

  1. 前往 Settings → Essentials
  2. 如果已连接，点击 Disconnect
  3. 等待 30 秒
  4. 重新输入凭据
  5. 再次点击 Connect

Cloudbeds 在 OAuth 前保存失败​

你会看到： "Failed to save settings before connecting: ..."

原因： AVA 会在开始 Cloudbeds OAuth 前保存其他未保存的 Essentials 更改。 详细信息会指出保存失败的设置。

处理方法：

  1. 阅读完整的错误横幅。

  2. 修正信息中指出的设置。

  3. 如果 AVA 显示保存操作，请保存该设置。

  4. 再次选择 Connect to Cloudbeds。

    ✓ 预连接保存成功后，Cloudbeds 应会打开。

Cloudbeds OAuth 交换失败​

你会看到： 连接显示 Version is required，或拒绝授权码交换。

原因： Cloudbeds 授权码只能使用一次。 失败的回调无法重放。 AVA 现在会将省略的 Cloudbeds OAuth 版本默认为 v3。

处理方法：

  1. 前往 Settings → Essentials。

  2. 选择 Connect to Cloudbeds。

  3. 登录 Cloudbeds，然后选择 Authorize 或 Allow。

  4. 完成连接。Cloudbeds 会生成新的授权码。

  5. 如果新连接再次失败，请联系支持。

    ✓ Cloudbeds 连接应会完成，无需你输入版本。

Cloudbeds v1 或 v2 被拒绝​

你会看到： AVA 显示不支持的 Cloudbeds 版本错误。

原因： Cloudbeds v1 和 v2 适配器已停用。 不指定版本的 Cloudbeds 路由使用 v3。

处理方法：

  1. 清除任何明确的 Cloudbeds 版本设置或固定值。

  2. 请集成管理员移除 v1 或 v2 调用方固定值。

  3. 前往 Settings → Essentials。

  4. 选择 Connect to Cloudbeds，再次完成授权。

    ✓ 新连接使用 Cloudbeds v3。

PMS 设置保存未完成​

你会看到： AVA 接受 PMS 详情后显示缓存或服务错误。

原因： AVA 会在完成保存前，跨 PMS 服务确认更新后的设置。 保存成功后，较早的进行中刷新无法恢复以前的凭据。

处理方法：

  1. 等待一分钟后再试。

  2. 刷新 Settings → Essentials → PMS Integration。

  3. 除非要替换凭据，否则不要修改已遮罩的凭据。

  4. 再次点击 Save。

  5. 确认成功信息后，再使用依赖 PMS 的流程。

    ✓ 保存成功后，新凭据应可在 AVA 的各服务器上正常工作。

如果尝试三次后仍显示相同错误，请联系支持。 请附上完整错误信息、PMS 提供商和保存失败的时间。

更改凭据后出现 eZee 代码 611​

你会看到： 更新 PMS 凭据后，eZee 返回 611、"Invalid Auth Code or Hotel Code"。

原因： 较早的 PMS 请求可能仍在使用旧凭据快照完成。 保存后，AVA 会将该快照标记为过期。

处理方法：

  1. 确认 Hotel Code 和 Auth Code 属于同一个 eZee 酒店。

  2. 前往 Settings → Essentials → PMS Integration。

  3. 保存更新后的凭据。

  4. 等待成功信息。

  5. 只重试一次 PMS 操作。

    ✓ 下一次 PMS 操作应使用新凭据。

如果保存成功后代码 611 仍存在，请联系支持。

达到速率限制​

你会看到： 429 错误、限流信息，或包含重试时间的请求。

原因： Cloudbeds 或 AVA 自身的请求预算暂时限制了请求。 如果可用，AVA 会保留任一来源的重试时间。 AVA 还会为不同功能区域保留独立的请求预算，因此一个繁忙页面不太可能拖慢另一个页面。 房间分配和最终办理入住也会自动重试临时的 PMS 429。 这些操作在继续或显示错误前可能需要多等待几秒。 当 AVA 自身 bucket 为空时，其他一些面向住客的调用也会短暂等待。 这只适用于本地短促突发，不适用于供应商冷却时间。 如果 Cloudbeds 多次返回相同的访问错误，AVA 会短暂暂停下一次重试。

限流隔离

如果某个页面持续显示 429，问题通常只限于该页面或功能区域。 等待期间，AVA 的其他部分可能仍正常工作。

处理方法：

  1. 等待错误中显示的重试时间。

  2. 刷新页面一次。

  3. 再次尝试该操作。

  4. 如果问题重复出现，等待几分钟后再重试。

  5. 如果没有显示重试时间，将其视为短暂限流，稍后再试。

    ✓ 重试时间过后且请求预算可用时，请求应会成功。

在分配房间或最终办理入住期间

先让当前操作完成，再选择 Retry。 如果 AVA 仍显示友好的房间分配错误，请在 PMS 中检查预订。 然后刷新 AVA，只重试受影响的步骤一次。

Cloudbeds 访问错误​

你会看到： Cloudbeds 访问信息（例如 You don't have access to property ID）持续返回。

原因： 已连接的 Cloudbeds 账号无法读取该酒店。 AVA 会暂停重复重试，避免相同失败不断请求 Cloudbeds。

处理方法：

  1. 确认你登录的是正确的 Cloudbeds 酒店。

  2. 请 Cloudbeds 管理员核实酒店访问权限。

  3. 等一分钟后再试。

  4. 修复访问问题后刷新一次。

    ✓ Cloudbeds 接受请求后，下一次连接尝试应会成功。

你会看到 → 处理方式

你看到的内容处理方式
错误出现一次等待重试时间，然后再试
错误持续出现暂停几分钟，然后重试
预订仍未加载查看 同步问题

Cloudbeds Webhook 凭据被拒绝​

你会看到： Cloudbeds 持续接受连接，但保存设置后 webhook 修复失败。

原因： Cloudbeds 接受了登录，但没有接受 AVA 所需的 webhook 权限。

处理方法：

  1. 从 Settings → Essentials 重新连接 Cloudbeds。

  2. 再次完成 Cloudbeds 授权提示。

  3. 再次保存已启用的到店前设置。

  4. 如果仍失败，请 Cloudbeds 管理员检查应用权限。

    ✓ 权限刷新后，webhook 修复应会正常完成。

预订未同步​

你会看到： 连接后没有预订出现，或预订缺失。

快速修复​

  1. 在 Operations View 中点击 Refresh
  2. 等待 5-10 分钟完成初次同步
  3. 确认 PMS 中今天有预订

检查 PMS 设置​

  1. 前往 Settings → Essentials
  2. 滚动到 PMS Integration 区域
  3. 确认连接状态显示 "Connected"
  4. 检查同步设置配置正确

仍未解决？​

  • 确认 AVA 中查看的预订日期与 PMS 中的日期一致
  • 检查 PMS 中的预订状态是否允许同步（confirmed，而不是 cancelled）
  • 确认住客人数大于 0

同步延迟​

你会看到： 预订延迟出现。

正常情况​

大多数 PMS 系统每 5-15 分钟同步一次。是否支持实时同步取决于：

  • 你的 PMS 套餐等级
  • 具体 PMS 提供商

减少延迟​

  1. 需要时使用手动刷新
  2. 联系 PMS 提供商确认是否支持实时 API
  3. 在低活跃时段安排同步

身份验证错误​

你会看到： "Invalid credentials" 或 "Authentication failed"

Cloudbeds​

  1. 登录 Cloudbeds
  2. 前往 Settings → Integrations → API
  3. 生成新的 API 凭据
  4. 准确复制凭据（如有复制按钮，请使用该按钮）
  5. 不做修改，直接粘贴到 AVA

Opera Cloud​

  1. 等待最多 30 秒，让 AVA 完成自动重试。 这包括一次临时 OAuth 超时或网关错误。

  2. 只有错误仍存在时才重试操作。

  3. 确认环境 URL 正确（test 或 production）。

  4. 确认 client ID、client secret、hotel ID 和 enterpriseId 正确。

  5. 在 Settings → Essentials → PMS Integration 中重新输入凭据，然后点击 Save。

  6. 如果错误仍显示，请联系 Oracle 代表。

    ✓ 一次性临时错误或缓存凭据失败可能无需断开 Opera 就能恢复。

Mews​

  1. 登录 Mews Commander
  2. 前往 Settings → Integrations
  3. 找到 Vouch AVA 并重新生成 access token
  4. 在 AVA 设置中更新 token

何时联系支持​

如果满足以下情况，请联系支持：

  • 你已经尝试了所有排错步骤
  • 错误信息提到系统错误或技术问题
  • PMS 更改超过 30 分钟仍未反映

邮箱： success@vouch-technologies.com

请附上：

  • 错误信息截图
  • PMS 类型（Cloudbeds/Opera/Mews）
  • 问题开始时间
  • 你已经尝试过的步骤