错误处理

API 调用失败时，GoodVision 返回 HTTP 状态码和 Problem Details 错误信息。请根据状态码和错误码处理失败；detail 用于补充说明，不应用于程序判断。

常见响应

状态码	含义	调用方处理
400	请求格式或必填字段错误	修正输入，不要原样重试
401	缺少认证或 Token 无效	获取 Issuer/Audience 正确的新 Token
403	已认证但无权访问	检查 Scope、Organization、ProductAccess 和资源归属
404	资源不存在或对当前调用方不可见	核对 ID 和授权租户上下文
409	状态、版本或幂等冲突	读取最新状态后再决策
422	业务规则校验失败	根据错误码修正业务输入
429	超出配额	遵守 Retry-After 并退避
5xx	服务端暂时不可用	仅按接口说明重试临时故障

开发者后台恢复

后台登录过期、近期验证不足和权限撤销需要不同处理。按页面的错误提示恢复原范围，不要通过切换账号或企业绕过拒绝。

情况	处理方式
401，登录已过期	在原页重新登录；同一账号、同一有效范围可保留普通草稿，Secret 和敏感确认清除
403，明确提示需要近期身份验证	完成敏感操作验证，回到原页核对并再次明确提交
403，企业或应用权限撤销	停止原范围操作并清除旧资料；联系当前所有者或管理员核对权限
409，版本或状态冲突	读取最新状态，再核对操作；不要继续提交旧配置
超时或写入结果未知	保留原内容和操作编号，使用页面的“恢复原请求”或“重试原请求”；不要另建一次操作
依赖暂不可用	保留已验证登录并重新读取；故障不代表没有企业或没有权限

验证成功不会自动重放创建、保存、删除、付款、回复或转交。换账号、退出或原范围失效会清除旧草稿。普通 API 的 401 仍按上表获取正确 Token；后台 Session 恢复不能替代业务 API 授权。

原未知请求恢复时若遇到登录过期或近期验证要求，先完成验证，再明确恢复同一请求。原内容、版本和操作编号保持；验证成功不表示此前写入失败。页面明确指出输入无效时，修正对应字段后再提交新请求。

需要协助时，在当前应用提交技术反馈，附上安全诊断信息。平台客服只有在明确转交后才能参与。

建议保留的诊断信息

• request_id 或 correlation_id；
• operation_id、delivery_id 或 event_id；
• HTTP 状态码和机器错误码；
• Endpoint 名称和 UTC 时间；
• Application ID 和环境。

日志和支持请求中不得包含 Access Token、Client Secret、Webhook Secret、私钥或完整客户 Payload。

有效 Token 返回 403

有效 Token 只表示身份认证通过。收到 403 时，依次检查：

1. Audience 和 Scope 是否匹配目标 API。
2. 当前企业成员关系（Organization Membership）是否有效。
3. ProductAccess、Delegation 和具体资源权限是否允许本次操作。

使用当前用户自己的 Session 和 Token 排查。不要使用他人会话、伪造企业请求头或共享高权限 Token 绕过拒绝。

登录后的空间解析失败

用户与客户空间返回 401 时重新登录当前应用；403 时停止当前范围操作并确认应用或成员关系；503 时保留已验证登录，提供重新读取入口。不要回退开发者企业或静默切空间。用户上下文不要求额外 API Subscription，业务 API 的权限检查继续独立执行。