服务能力与错误处理
9 服务能力接口
9.1 查询服务说明和调用限制
GET /capabilities
无请求体。查询服务支持的运行模式及调用限制。apiVersion 为协议标识字符串，simulationTimeUnit 为仿真时间单位，us 表示微秒。runModes 数组给出各模式的最小与最大倍速，以及是否要求有限结束时刻。
limits 中 maximumPageSize、maximumEntityNames、maximumStatisticProperties 分别为页大小、单次对象名称数和统计属性数上限；maximumResponseBytes 为响应字节上限，resultRetentionMinutes 为终态运行数据保留分钟数。限制值应从服务响应读取，不能固定使用示例数值。调用频率与并发实例额度由服务提供方提供；HTTP 429 时按 Retry-After 响应头等待。
animation 中 animationTypes 给出动作类型，simulationTimeUnit=us 表示动作时刻采用仿真微秒，durationUnit=s 表示动作时长采用仿真秒，rotationRepresentation=EULER_XYZ_DEGREES 表示旋转采用以度计量的 XYZ 欧拉角，clockIncludedInResponses 表示响应附带时钟。实体的 supportedActions 给出实际适用动作，具体结构见第 7 章。
scripts 中 sourceTypes 和 language 给出脚本来源及语言；maximumCodeCharacters 是代码字符数上限，maximumParameterBytes 和 maximumResultBytes 是参数及结果的 UTF-8 JSON 字节上限，maximumExecutionsPerSimulation 和 maximumActiveExecutionsPerSimulation 分别限制不同幂等键的累计执行数和同时执行数。nameLookup 给出名称匹配规则及单次名称查询数量上限；exactMatch=true、caseSensitive=true、trimWhitespace=false 分别表示精确匹配、区分大小写、不自动删除空白。
coordinates 和 resourceBinding 说明空间基准与资源绑定；runModes.visualization 表示相应运行模式是否产生动画；maximumUpdatesPerPoll 给出增量批次上限。
10 错误处理
10.1 请求失败与运行故障
| 层次 | 判断字段 | 处理方式 |
|---|---|---|
| 接口请求失败 | 非 2xx HTTP 状态及响应 code | 按错误码处理参数、权限或服务问题；保留 requestId。请求失败本身不等于实例已经 FAILED |
| 仿真实例失败 | 实例 status=FAILED | 本次运行进入终态，不能继续或重新启动；读取 statusReasonCode 和 runtimeAvailable，保留可读取的结果与诊断标识，修正原因后创建新实例 |
| 模拟对象故障 | 对象 operatingState=FAILED | 表示该对象在模型中的故障状态，可用于故障时长和状态比例统计；仿真实例可继续运行，以实例 status 为准 |
| 某项指标无数据或不适用 | series.status=NO_DATA / NOT_SUPPORTED 等 | 按每条序列的状态展示，不用零值替代；其他对象或指标的数据仍可使用 |
FAILED 实例在故障发生前形成的数据属于未完成运行结果，不能作为正常完成运行的最终结果。其保留时间遵循同一资源保留规则；stop 可提前释放。场景加载失败直接返回创建错误，不返回一个可启动的新实例。
网络超时表示调用结果尚未确认。创建请求使用相同 Idempotency-Key 和相同参数重试；控制操作先查询实例状态，再按其幂等规则处理。不要把超时、空数组或单个设备故障直接解释成整个仿真失败。
10.2 请求错误示例
以下请求把 REAL_TIME 倍速设为 101，超出 1～100 范围。响应为参数错误；已有实例是否仍在运行，需要查询实例状态。
10.3 错误码与处理方式
| HTTP | code | 客户端处理 |
|---|---|---|
| 400 | INVALID_REQUEST | 按字段约束修正请求 |
| 400 | SCRIPT_COMPILATION_FAILED | 修正脚本代码，以新幂等键执行 |
| 400 | IDEMPOTENCY_KEY_MISSING | 为创建实例或提交脚本的请求补充幂等键 |
| 400 | INVALID_VISUALIZATION_CURSOR | 使用快照或增量响应中的完整游标，不自行增加序号 |
| 400 | INVALID_RUN_MODE_PARAMETERS | 修正模式与参数组合 |
| 400 | FULL_SPEED_END_TIME_REQUIRED | 提供有限正结束时间 |
| 400 | PAGE_OUT_OF_RANGE | 减小页码或页大小 |
| 401 | API_KEY_MISSING、API_KEY_INVALID | 核对凭证是否正确填写 |
| 403 | API_KEY_EXPIRED、API_KEY_DISABLED、SIMULATION_ACCESS_DENIED | 凭证失效时联系服务提供方；实例访问被拒绝时使用创建该实例的 Key |
| 404 | SCENE_NOT_FOUND、SIMULATION_NOT_FOUND、TABLE_NOT_FOUND | 核对标识并按需要重新发现资源 |
| 404 | ENTITY_NOT_FOUND、SCRIPT_NOT_FOUND | 核对当前实例中的对象名称或 Script 名称 |
| 409 | IDEMPOTENCY_KEY_REUSED | 同一业务重试保持参数；新业务使用新幂等键 |
| 409 | REQUEST_IN_PROGRESS | 等待后以原幂等键重试 |
| 409 | INVALID_SIMULATION_STATE | 先查询状态，再选择合法操作 |
| 409 | ENTITY_NAME_AMBIGUOUS、TABLE_NAME_AMBIGUOUS | 消除同名歧义；表格可补充所属对象名称 |
| 409 | SCRIPT_EXECUTION_IN_PROGRESS | 等待当前脚本结束，再提交另一脚本；不因冲突重复受理同一请求 |
| 409 | VISUALIZATION_GENERATION_CHANGED、VISUALIZATION_CURSOR_EXPIRED | 重新获取动画快照并替换客户端状态 |
| 410 | SIMULATION_RUNTIME_RELEASED | 运行数据已释放，需要时创建新实例 |
| 413 | RESULT_TOO_LARGE | 缩小请求范围；无法缩小时联系服务提供方 |
| 422 | SCENE_INVALID、SCENE_LOAD_FAILED、UNSUPPORTED_FIELD_VALUE | 核对场景数据并携带 requestId 联系服务提供方 |
| 422 | SCRIPT_LANGUAGE_NOT_SUPPORTED | 选择使用 Groovy 的 Script |
| 429 | RATE_LIMIT_EXCEEDED、ACTIVE_SIMULATION_LIMIT_EXCEEDED | 按 Retry-After 等待，或释放不再使用的实例 |
| 429 | SCRIPT_EXECUTION_LIMIT_EXCEEDED | 该实例不同幂等键的累计执行数已达上限，需要继续执行时创建新实例 |
| 500 | SCRIPT_EXECUTION_FAILED | 检查脚本及实例状态，保留 requestId；之前的修改可能已生效 |
| 500 | ENGINE_OPERATION_FAILED | 查询实例状态，保留 requestId 并联系服务提供方 |
| 502 | SCRIPT_RESULT_UNAVAILABLE | 脚本已结束但结果无法返回；不要自动重复业务操作 |
| 502 | RUNTIME_DATA_READ_FAILED | 查询实例状态，保留 requestId 并反馈 |
| 502 | ANIMATION_DATA_INVALID、VISUALIZATION_STREAM_FAILED、VISUALIZATION_UNSUPPORTED_ACTION | 动画数据无法转换；保留 requestId，停止推进游标并联系服务提供方 |
| 503 | OPEN_API_UNAVAILABLE、SCENE_SERVICE_UNAVAILABLE | 按退避策略重试；创建使用原幂等键 |
statusReasonCode 与错误 code 职责不同：END_TIME_REACHED 表示达到结束时刻，SIMULATION_COMPLETED 表示正常完成，STOP_REQUESTED 表示请求停止，ENGINE_RUNTIME_ERROR、ENGINE_INSTANCE_LOST 等表示失败原因。运行中若出现未知错误，保留原始 HTTP 状态、code 和 requestId，避免仅根据 message 自动重试非幂等操作。
创建请求网络超时或 503 时，复用原幂等键和原参数；429 按 Retry-After 等待。控制请求的网络结果不明确时，先查询状态。start 相同有效参数、pause、resume、stop 遵循上述幂等语义；不要因响应未收到就发起另一场运行。
脚本异步受理后的失败记录见 脚本状态与结果。HTTP 2xx 与 code=OK 表示请求层成功，脚本业务仍须检查 data.status。动画读取错误时保留原游标，重建快照后再继续。
接口参考与调用示例
以下为结构示例，未代表当前环境实测。路径中的标识和请求变量使用本次响应或获授权的配置。
查询服务能力
GET /simulation/openapi/v1/capabilities
取得服务地址与有权限的凭证后先读取本接口；不创建实例。
请求参数
认证头 X-Foresim-Api-Key 由调用方服务端添加；可选 X-Request-Id 用于关联请求。当前接口没有查询字符串参数。
无请求体，不发送空 JSON 代替省略。
请求示例
双花括号是测试页变量，发送时替换；下列模板尚未发送。
GET /simulation/openapi/v1/capabilities
X-Foresim-Api-Key: <api-key>
Accept: application/json
成功响应结构
首次成功 HTTP 200；外层 code=OK。下方是结构示例，值与空数组不代表实测数据。
{
"code": "OK",
"message": "Success",
"requestId": "example_request",
"data": {
"apiVersion": "example",
"simulationTimeUnit": "example",
"coordinates": {
"handedness": "example",
"upAxis": "example",
"lengthUnit": "example",
"rotationRepresentation": "example",
"transformSpace": "example"
},
"runModes": [],
"limits": {
"maximumPageSize": 0,
"maximumEntityNames": 0,
"maximumStatisticProperties": 0,
"maximumUpdatesPerPoll": 0,
"maximumResponseBytes": 0,
"resultRetentionMinutes": 0
},
"visualizationChangeTypes": [],
"resourceBinding": "example",
"animation": {
"eventTypes": [],
"channelProperties": [],
"channelTiming": "example",
"rotationInterpolation": "example",
"clockIncludedInResponses": false
},
"scripts": {
"sourceTypes": [],
"language": "example",
"maximumCodeCharacters": 0,
"maximumParameterBytes": 0,
"maximumResultBytes": 0,
"maximumExecutionsPerSimulation": 0,
"maximumActiveExecutionsPerSimulation": 0
},
"nameLookup": {
"exactMatch": false,
"caseSensitive": false,
"trimWhitespace": false,
"maximumEntityNames": 0
}
}
}
展开完整响应字段定义
| 字段 | 类型与约束 | 必填 | 说明 |
|---|---|---|---|
apiVersion | string | 是 | 见字段结构 |
simulationTimeUnit | string | 是 | 见字段结构 |
coordinates | object | 是 | 见字段结构 |
runModes | array | 是 | 见字段结构 |
limits | object | 是 | 见字段结构 |
visualizationChangeTypes | array | 是 | 见字段结构 |
resourceBinding | string | 是 | 见字段结构 |
animation | object | 是 | 见字段结构 |
scripts | object | 是 | 见字段结构 |
nameLookup | object | 是 | 见字段结构 |
典型失败与下一步
401 检查服务端凭证；403 检查来源和实例归属；400 检查 details 中的字段；409 检查状态、幂等键或名称歧义；410 表示资源已释放；429 按 Retry-After 停止并等待。保留实际 requestId。
{"code":"INVALID_REQUEST","message":"Invalid request","requestId":"example_error","details":[{"field":"request","reason":"检查必填字段和前置状态"}]}