服务器到服务器 API 响应代码和错误

关注
Avatar
Jared Ornstead
Updated
文件

响应代码

与 Singular 的应用程序接口集成时，所有响应都会返回 HTTP 200 状态代码，需要验证响应体的 "status "字段，以确定成功（"ok"）或失败（"error"）。

当状态为"error"时，响应有效载荷包括一个"reason "字段，提供详细的错误信息。

建议

  • 实施指数后退重试机制，配置最大尝试次数，排除不可重试的错误（如无效参数）。
  • 在重试期间保持请求顺序，以确保数据一致性。
  • 为进行适当的调试和监控，记录所有失败请求，包括原始参数、错误信息、设备标识符和时间戳。跟踪重试尝试，并针对重大故障实施通知系统。错误响应格式采用一致的 JSON 结构，包含状态和原因字段。

这种全面的错误处理策略可确保强大的 API 集成，同时保持数据的准确性，并提供对潜在问题的清晰可见性。

成功

以下是 API 对请求的成功响应。

HTTP 响应 
200 - ok

响应体中没有任何错误或原因的200 - ok表示请求已发送到队列中进行处理。

响应：
{
    "status": "ok"
}

错误

下面列出了 API 在响应请求时可能返回的错误信息。

HTTP 响应 
200 - error

200 - 错误响应代码，"原因 "为 "缺少参数：{参数}"。

此错误只针对特定参数，而非所有必填参数。

如果缺少参数或参数值丢失，则可能会收到缺少参数的错误信息。应解决该错误并重新发送请求。

响应：
{
    "status": "error",
    "reason": "missing argument: a"
}
 
200 - error

200 - 错误响应代码，"原因 "为 "平台无效：{平台}"。这意味着平台值无效。

应解决该错误并重新发送请求。

响应：
{
    "status": "error",
    "reason": "invalid platform: Desktop"
}
 
200 - error

200 - 错误响应代码，"原因 "为 "未提供设备标识符"。请求中未包含设备标识符。

应解决该错误并重新发送请求。

响应：
{
    "status": "error",
    "reason": "no device ID supplied"
}
 
200 - error

200 - 错误响应代码，"原因 "为 "平台：{platform} 应该有一个 {identifier} 参数"。该错误表示指定的平台没有正确的设备标识符。

应解决该错误并重新发送请求。

响应：
{
    "status": "error",
    "reason": "platform: PC should have an sdid param"
}
 
XXX

如果没有收到 200 - ok，则应重试请求。