帮助中心集成

为了: 管理员

处理 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该物品不存在,或者属于另一个中心站;或者正在被删除中;又或者您的客户端无法看到该物品。请检查身份证信息。
500InternalError:CaseActive中存在一个故障,相关开发者正在处理这个问题。请稍后再试,如果问题仍然存在,请联系客服支持。
503TransientException:这个中心系统有一段时间过于繁忙,无法处理其他任务。稍作等待后再次尝试,每次等待的时间可以逐渐延长。

如果通话时间超过30秒,系统会由于网络原因而中断通话,且不会返回任何JSON格式的数据。不过,通过在后台运行的方式可以避免这种情况。

为什么你知道某个物品存在却无法回答 404 个问题

中心键充当了中心的虚拟助手虚拟助手 一个自动化的团队成员,负责发布欢迎信息、签到信息和公司动态;其发布的帖子带有虚拟助理徽章。,它只能查看虚拟助手角色有权查看的内容。对于该角色不可见的项目,系统会返回404错误,就像这些项目不存在一样,因此API不会显示它们。今天,即使尝试编辑或删除已发布的发票,或者编辑已发布的电子签名文件,但如果相关项目对当前角色不可见,系统仍然会返回403错误。PublishAlreadyPublishedException中的列表功能也会忽略这些项目,无需特别说明。要了解某个角色的具体权限,可以使用管理键阅读role::bots的相关信息;详见如何使用管理键查看角色权限。

可以安全重试

  • 503,以及所有的TransientException,在短暂等待之后就会生效。
  • 400 TransactionCanceledException,这种情况是由于某些繁忙的时刻导致的。而一旦检查了情况后,会发现CaseUserLimitOrTransactionException并不为满值。
  • 500,稍晚一些。

请不要再次尝试处理那些仍然出现400错误、401错误、403错误或404错误的情况——因为这些请求仍会被拒绝。

相关文章

使用密钥验证 API 请求将您的密钥作为持有者令牌发送到管理面板的 API 获取管理密钥,或发送到门户网站的 API 获取中心密钥,并将其限制在您的 IP 地址范围内。集成了解 API 的功能了解管理密钥和中心密钥各自的权限范围,为什么每个密钥都充当虚拟助手,以及完整的技术清单在哪里。集成