为了: 管理员
处理 API 错误和状态码
阅读错误正文,了解 400、401、403、404、500 和 503 的含义,以及为什么您的密钥无法查看的项目会返回 404。
在本文中5 个部分
此页面介绍了两种API如何报告被拒绝的呼叫情况,无论是针对管理密钥还是中心密钥而言。
错误主体
每个被拒绝的呼叫都会返回一个状态代码以及一个JSON格式的数据体:
{
"error": {
"code": 400,
"message": "CaseReferenceIdExistsException",
"error_type": "ClientException",
"reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
}
}
| 场地 | 它包含什么 |
|---|---|
code | 还是那个状态代码 |
message | 该错误的名称例如为CaseReferenceIdExistsException。请让你的代码根据这一名称进行操作;它不会随着阅读器的语言而发生变化。 |
error_type | 错误类型如下:ClientException表示请求被拒绝,ApiException表示请求无效,SessionException表示缺少某个关键参数,ModelException表示某个关键参数未被提供,或者来自数据存储的拒绝响应,TransientException表示需要重试以解决短暂的问题,InternalError则表示在CaseActive过程中出现了故障。 |
reason | 如果有任何详细信息的话,可以说明一下:那些冲突的记录的标识符,或者第一个字段存在的问题。通常这些字段是空的。 |
errors | 对于无效请求,每个字段只允许有一个条目。 |
字段错误
如果请求中存在缺失或无效的字段,系统会返回400 SchemaFieldsException 状态码。每个字段都有一个 errors 标签来标识该字段的详细信息。location 标签用于标识字段的名称,多个字段之间通过点分隔;message 标签则用于说明出现问题的具体位置。
{
"error": {
"code": 400,
"message": "SchemaFieldsException",
"error_type": "ApiException",
"reason": "FieldRequiredException",
"errors": [
{"domain": "json", "location": "ref_id", "locationId": "ref_id", "locationType": "schema", "message": "FieldRequiredException", "reason": "FieldRequiredException"}
]
}
}
domain 是 json 为了身体着想…… query 关于该地址的参数设置。常见的字段错误包括:
message | 怎么了 |
|---|---|
FieldRequiredException | 它不见了,或者存在于无法被触及的地方,一片空白。 |
FieldValidatorFailedException | 其价值并非是可以被赋予的,比如角色、案例类型或你的中心所不具备的阶段等。 |
FieldMinLengthException, FieldMaxLengthException | 要么太短,要么太长。 |
FieldLimitTooLargeException | 一个列表的…… limit 超过1000个字符,这是页面所能容纳的最大字符数。 |
FieldEmailTypeException, FieldPhoneTypeException | 不是电子邮件地址,也不是带有国家代码的电话号码。 |
FieldNameTypeException | 一个无法被文字完全表达的名字 |
FieldPathSlugTypeException | 一个标签ID或参考ID,其字符应包含字母、数字、连号和斜杠以外的其他字符 |
FieldDateTypeException | 不是约会,比如2026-03-15 |
那些字段虽然存在于API中,但并未被识别或拒绝使用。因此,请务必对照文档确认字段名称的拼写是否正确。
状态码
| 地位 | 它的含义 | 该怎么办 |
|---|---|---|
| 400 | 请求无效,或者所提出的变更是不被允许的:可能是字段错误,也可能是系统拒绝了该请求。 message, 比如 CaseReferenceIdExistsException | 在再次发送之前请先纠正错误。 |
| 401 | 密钥本身被拒绝了;请参阅如何使用密钥进行API请求认证的相关说明。 | 停下,检查一下钥匙。 |
| 403 | 该密钥可能无法执行此操作:调用管理密钥时可能无法生效(BotNotAllowedException);锁定的集线器(对于管理密钥来说为ManageBillingInactiveException,而对于集线器密钥则需要在门户权限设置为只读后才能执行,BillingReadOnlyException);案件已关闭(CaseClosedException);或者进行的更改与同一时间发生的其他更改冲突了(ItemUpdateFailedException等情况)。 | 解决根本原因。如果还是发生冲突,请重新阅读相关说明,然后再次尝试。 |
| 404 | 该物品不存在,或者属于另一个中心站;或者正在被删除中;又或者您的客户端无法看到该物品。 | 请检查身份证信息。 |
| 500 | InternalError:CaseActive中存在一个故障,相关开发者正在处理这个问题。 | 请稍后再试,如果问题仍然存在,请联系客服支持。 |
| 503 | TransientException:这个中心系统有一段时间过于繁忙,无法处理其他任务。 | 稍作等待后再次尝试,每次等待的时间可以逐渐延长。 |
如果通话时间超过30秒,系统会由于网络原因而中断通话,且不会返回任何JSON格式的数据。不过,通过在后台运行的方式可以避免这种情况。
为什么你知道某个物品存在却无法回答 404 个问题
中心键充当了中心的虚拟助手虚拟助手 一个自动化的团队成员,负责发布欢迎信息、签到信息和公司动态;其发布的帖子带有虚拟助理徽章。,它只能查看虚拟助手角色有权查看的内容。对于该角色不可见的项目,系统会返回404错误,就像这些项目不存在一样,因此API不会显示它们。今天,即使尝试编辑或删除已发布的发票,或者编辑已发布的电子签名文件,但如果相关项目对当前角色不可见,系统仍然会返回403错误。PublishAlreadyPublishedException中的列表功能也会忽略这些项目,无需特别说明。要了解某个角色的具体权限,可以使用管理键阅读role::bots的相关信息;详见如何使用管理键查看角色权限。
可以安全重试
- 503,以及所有的
TransientException,在短暂等待之后就会生效。 - 400
TransactionCanceledException,这种情况是由于某些繁忙的时刻导致的。而一旦检查了情况后,会发现CaseUserLimitOrTransactionException并不为满值。 - 500,稍晚一些。
请不要再次尝试处理那些仍然出现400错误、401错误、403错误或404错误的情况——因为这些请求仍会被拒绝。