本文将为您介绍 THDS 在 FHIR 资源操作、搜索操作以及 Bundle 事务/批处理操作中可能返回的通用错误码。实际接口返回的错误信息可能会因资源类型、请求参数、业务规则和权限配置不同而有所差异，但总体遵循以下约定。
通用错误码说明
错误码 | 名称 | 说明 | 常见触发场景 |
400 | Bad Request | 请求格式错误，或请求参数不合法 | 请求体 JSON 结构错误、资源 ID 非法、搜索参数格式错误、补丁路径错误、Bundle 结构错误 |
401 | Unauthorized | 未认证，缺少有效身份凭证 | 未传认证信息、认证令牌无效、认证令牌已过期 |
403 | Forbidden | 已认证但无权访问目标资源或操作 | 无创建、更新、删除、检索或事务执行权限 |
404 | Not Found | 请求的资源、资源类型或路径不存在 | 指定资源不存在、目标接口路径错误、事务条目中的目标资源不存在 |
409 | Conflict | 当前资源状态或匹配结果与操作要求冲突 | 版本冲突、条件创建匹配不唯一、条件更新匹配不唯一、事务中条目冲突 |
410 | Gone | 资源或指定历史版本已不可访问 | 资源已逻辑删除、历史版本不可访问 |
415 | Unsupported Media Type | 请求内容类型不受支持 | 未使用 application/fhir+json、未使用 application/json-patch+json |
422 | Unprocessable Entity | 请求语法正确，但未通过业务或规则校验 | FHIR 资源结构不完整、业务约束不满足、搜索表达式可解析但不可执行 |
500 | Internal Server Error | 服务端内部处理异常 | 服务执行异常、事务处理异常、未知内部错误 |
按接口类型说明
资源基础操作
适用于
Create、Read、vRead、Update、Delete、Patch 等资源级接口。常见情况如下：400 Bad Request：创建或更新时提交的资源内容不符合 JSON/FHIR 结构要求；读取、删除时资源 ID 非法；Patch 时 op、path 或补丁文档格式错误。403 Forbidden：当前调用方没有对应资源的创建、读取、更新、删除权限。404 Not Found：指定资源不存在，或请求的资源类型端点不存在。409 Conflict：更新时发生版本冲突，删除时当前资源状态不允许删除，Patch 时目标路径与资源当前状态不匹配。410 Gone：读取的资源或历史版本已不可访问。415 Unsupported Media Type：创建、更新未使用 application/fhir+json，或 Patch 未使用 application/json-patch+json。422 Unprocessable Entity：资源内容语法正确，但未通过业务规则或 FHIR 规则校验。搜索操作
适用于基础搜索、引用搜索、数值搜索、日期时间搜索、分页、排序、全文搜索以及患者全量信息检索等接口。常见情况如下：
400 Bad Request：搜索参数格式错误，或参数值不合法，例如日期比较前缀错误、数值表达式错误、排序字段错误、分页参数错误。403 Forbidden：当前调用方没有搜索对应资源或访问患者全量信息的权限。404 Not Found：指定资源类型不存在，或目标患者不存在。422 Unprocessable Entity：搜索语法正确，但未通过业务规则、权限规则或资源级约束校验。Bundle 事务与批处理操作
适用于基础 Bundle 事务、捆绑多个关联资源、占位符 ID 与引用、条件创建、条件更新、事务内删除、事务内 Patch 等接口。常见情况如下：
400 Bad Request：Bundle 结构错误、条目请求格式错误、占位符 ID 非法、引用路径不合法、条件表达式格式错误。404 Not Found：Bundle 条目中的目标资源路径不存在，或事务操作目标资源不存在。409 Conflict：资源 ID 冲突、引用关系冲突、条件创建/条件更新匹配不唯一，或事务中某一删除条目失败导致整体回滚。422 Unprocessable Entity：Bundle 语法正确，但资源内容、引用关系或业务规则校验失败。使用建议
在调用写入类接口前，确认
Content-Type 与请求体结构符合要求。在执行更新、删除、Patch 和事务操作前，确认目标资源存在且当前调用方具备操作权限。
在使用搜索、条件创建、条件更新等接口时，尽量保证搜索条件具备明确性和唯一性。
在处理
409、422 等错误时，建议结合具体响应内容进一步定位字段级或业务级问题。
