Saydo REST状态码
以下部分描述了通过Saydo REST 消息传递向 PubSub+ 事件代理发送 REST 消息或从 PubSub+ 事件代理接收 REST 消息时的状态码和错误响应处理。它还讨论了 REST 客户端的期望和要求，以确保与事件代理的正确互操作。
Saydo HTTP状态码概述
当通过Saydo REST消息传递向PubSub+事件代理发布消息时，事件代理遵循RFC 2616中定义的状态码定义，并遵循HTTP规范中的指南。
事件代理向REST HTTP客户端返回的HTTP响应
PubSub+事件代理向REST HTTP客户端返回的HTTP状态码
| 状态码 | PubSub+ 事件代理行为 |
|---|---|
| 成功 2xx | PubSub+ 事件代理返回 200 OK 状态码表示消息处理成功。 |
| 重定向 3xx | PubSub+ 事件代理不会返回任何 3xx 状态码。 |
| 客户端错误 4xx | PubSub+ 事件代理返回 4xx 状态码和详细响应字符串，用于客户端似乎出错的情况。通常，在未先修正错误情况之前，重新尝试这些请求是没有意义的。 |
| 服务器错误 5xx | PubSub+ 事件代理返回 5xx 状态码和详细响应字符串，用于事件代理在处理请求时遇到错误的情况，即使从客户端角度看请求似乎正确。这可能是临时或永久条件。例如，事件代理可能暂时没有资源来处理请求。通常，重新尝试这些请求是有意义的，因为条件可能已经清除。 |
| 其他状态码 | 随着 Solace REST 消息传递的发展，Solace 保留引入新状态码处理的权利。 |
REST消费者向事件代理返回的HTTP响应
REST 消费者向 PubSub+ 事件代理返回的 HTTP 状态码
| 状态码 | PubSub+ 事件代理行为 |
|---|---|
| 成功 2xx | PubSub+ 事件代理将 200、201、204 或 205 状态码视为表示消息处理成功。它将所有其他 2xx 状态码视为错误场景，并遵循正常的消息错误处理。 |
| 重定向 3xx | PubSub+ 事件代理不期望 3xx 状态码。如果 REST 消费者响应 3xx 状态码，行为是未定义的。 |
| 客户端错误 4xx | PubSub+ 事件代理将 4xx 状态码视为错误场景，并遵循正常的消息错误处理。 |
| 服务器错误 5xx | PubSub+ 事件代理将 5xx 状态码视为错误场景，并遵循正常的消息错误处理。 |
| 其他状态码 | PubSub+ 事件代理不期望上述列表之外的状态码。如果 REST 消费者响应其他状态码，行为是未定义的。 |
REST HTTP客户端请求到PubSub+事件代理
成功
当 PubSub+ 事件代理成功从 REST 生产者接收 REST 消息时，它会返回 200 OK 状态码。
对于持久和非持久消息，这意味着事件代理已成功将入站消息存储在其消息池中，并且事件代理保证该消息的传递。也就是说，只有在成功将入站消息放入池后，才会返回 200 OK。
对于直接消息，200 OK 在事件代理成功从经过身份验证的连接读取并解析完整的 HTTP POST 请求后返回。如果 HTTP 连接未经身份验证，或者连接的会话参数（身份验证和/或客户端名称）正在更改，则在身份验证处理完成之前，事件代理不会返回任何 POST 响应。事件代理在任何进一步处理 之前响应 200 OK。因此，对于直接消息，客户端知道事件代理已接受消息为正确格式化和经过身份验证的消息。如果事件代理稍后因其他原因（例如消息主题的 ACL 拒绝）丢弃此直接消息，客户端将不会收到通知。事件代理在事件代理的统计信息中跟踪丢弃原因。
在请求/回复场景中，只有在事件代理收到回复消息后，才会返回 200 OK 响应。回复的内容包含在 200 OK 响应的正文中。
失败
通常，对于所有需要 PubSub+ 事件代理向 REST HTTP 客户端发送非 200 OK HTTP 响应的失败情况，响应文本位于 HTTP 响应头中（可能是摘要形式）和 HTTP 响应正文中（可能有更多详细信息）。下面的表格更详细地概述了预期的错误代码。
对于向 Solace 发送的单个 HTTP POST 请求，可能会发生两种类型的失败：
- 身份验证失败
- 消息传递失败
通常，身份验证失败仅在新的 HTTP REST 连接上的第一个 HTTP POST 请求发生，或者在后续 HTTP 请求中会话参数发生变化时发生。消息传递失败可能发生在任何消息上。
Solace PubSub+ 事件代理还会在发生故障时在 HTTP 响应正文中返回错误响应详细信息。请参阅 HTTP 响应正文格式。
身份验证失败
下表提供了 REST HTTP 客户端在连接到事件代理时可能遇到的部分失败代码。提供的描述应足以正确识别失败的根本原因。
REST 生产者连接失败代码
| 错误码 | 描述 |
|---|---|
| 403 未授权 | 客户端身份验证失败。 |
| 403 客户端用户名已关闭 | 客户端的用户名已在事件代理上被管理员关闭。 |
| 403 基本身体验证已关闭 | 客户端尝试连接到已关闭基本身份验证的事件代理。 |
| 403 客户端证书身份验证已关闭 | 客户端尝试连接到已关闭客户端证书身份验证的事件代理。 |
| 403 客户端名称已在使用中 | REST HTTP 客户端尝试使用已被事件代理上的另一个客户端使用的客户端名称。客户端名称必须在消息 VPN 中是唯一的。 |
| 403 禁止 | 由于事件代理上给定用户名/消息 VPN 的 ACL 配置为拒绝使用提供的 IP 地址/子网掩码的客户端，客户端登录到事件代理上的消息 VPN 被拒绝。 |
| 503 消息 VPN 不可用 | REST HTTP 客户端连接到的事件代理上的消息 VPN 当前已关闭。 |
在向事件代理发送 HTTP POST 请求时的消息传递失败
REST 生产者发布失败代码列出了一些 REST HTTP 客户端在向事件代理发送请求时可能遇到的最常见失败代码。这不是所有可能失败代码的完整枚举。通常，发送保证消息的 REST HTTP 客户端可以收到与向 Solace PubSub+ 事件代理发送消息的普通 SMF 客户端可以收到的所有失败代码。
对于来自 REST 生产者的直接消息，响应是在事件代理从 HTTP 连接读取并解析消息并执行任何必要的身份验证处理后 返回的。因此，对于直接消息，即使事件代理响应了 200 OK，事件代理也可能会稍后丢弃该消息。此丢弃将由事件代理统计信息跟踪，并且与其他事件代理客户端的行为类似。唯一的例外是直接消息请求/回复消息交换模式，其中 HTTP 响应会延迟，直到事件代理收到回复。在更多场景中会将详细的错误代码返回给 REST 生产者。
失败代码中的解释应足以正确识别失败的根本原因。在下表中，“D” 列表示错误代码适用于直接消息，“G” 列表示错误代码适用于保证消息（即持久和非持久消息）。
REST 生产者发布失败代码
| 错误码 | 描述 | D | G |
|---|---|---|---|
| 400 错误的请求 | HTTP 请求格式不正确。消息正文中提供了原因的详细信息。 | Y | Y |
| 400 主题解析错误 | 使用的主题语法不受支持。 | Y | Y |
| 400 消息过长 | 客户端尝试发送的消息大于事件代理支持的大小。 | Y | Y |
| 400 未找到队列 | REST 生产者尝试向未知队列发送 POST 请求。 | N | Y |
| 403 发布 ACL 被拒绝 | 由于事件代理上给定用户名和消息 VPN 的 ACL 中定义的主题与消息的主题匹配，因此 REST 生产者的消息无法发布。 | N | Y |
| 405 不允许的方法 | 事件代理仅接受 POST 请求方法。其他 HTTP 请求方法不受支持，并会引发此错误。 | Y | Y |
| 408 请求超时 | 事件代理在尝试从 REST HTTP 客户端读取 HTTP POST 请求时超时。 | Y | Y |
| 500 内部服务器错误 | HTTP POST 请求无法处理的原因还有其他。应将问题报告给 Solace 支持以进行调查。 | N | Y |
| 503 消息池超出配额 | 由于保证消息池超出了其分配的空间配额，因此未投递消息。 | N | Y |
| 503 队列已关闭 | 尝试对已关闭的队列进行操作。 | N | Y |
| 503 服务不可用 | 事件代理上未启用保证消息传递服务。 | N | Y |
| 504 网关超时 | 事件代理在等待预期的回复消息时超时。 | Y | Y |
HTTP 响应正文格式
除了上面描述的 HTTP 响应头中提供的信息外，当 PubSub+ 事件代理未能成功从 REST HTTP 客户端接收 REST 消息时，事件代理会在 HTTP 响应正文中提供错误响应详细信息。根元素是 <solace-error-response> 元素。此元素最多可以有三个子元素。
REST 响应正文 XML 详细信息
| XML 元素 | 描述 |
|---|---|
| code | 失败的 HTTP 状态码。 |
| reason | 失败的 HTTP 状态消息。 |
| detail | 提供与问题相关的额外详细信息的失败文本描述，以人类可读的文本形式。 |
| 内部使用 | 值是 PubSub+ 版本特定的 ID，用于辅助内部 Solace 调试。 |
以下示例显示了 Solace 错误响应正文：
<solace-error-response>
<code>403</code>
<reason><![CDATA[发布 ACL 被拒绝]]></reason>
<detail><![CDATA[
主题 "/QUEUE/acl/topic";
SMF AD 控制客户端 ACK 响应错误
]]></detail>
<internal-use>2:10960</internal-use>
</solace-error-response>
事件代理终止HTTP连接
PubSub+ 事件代理出于以下原因终止 REST HTTP 客户端的 HTTP 连接：
- HTTP 头解析错误 - 收到的 HTTP 头格式无效，无法解析。因此，无法继续进行 REST 会话。REST 客户端在与事件代理通信时必须发送正确格式的 HTTP。
- 身份验证等待超时 - 如果 REST 客户端打开到 PubSub+ 事件代理的 HTTP 连接，事件代理不会无限期地等待客户端身份验证。经过一段时间后，事件代理将关闭 REST HTTP 客户端连接。
- 完整消息等待超时 - 当从 HTTP 客户端连接读取时，PubSub+ 事件代理不会无限期地等待 HTTP 请求完成。经过一段时 间后，如果事件代理仅收到部分请求，则会关闭 REST HTTP 客户端会话。
- Solace 事件代理管理中的各种关闭（包括用户名、消息 VPN、服务等）、管理断开连接或活动切换。这些会立即生效，即使事件代理尚未完成发送 HTTP POST 响应。
- 慢客户端 - 如果整个事件代理资源不足，任何消耗大量资源但无法跟上提供的流量负载的客户端都可能断开连接。例如，如果 REST HTTP 生产者发送同步请求/回复消息，并且回复消息具有较大的有效载荷，但 REST HTTP 生产者在消耗该有效载荷时速度较慢（无论是因为客户端无法接受还是客户端方向存在网络问题），则 REST HTTP 生产者的连接可能会因慢客户端而被断开。
事件代理向REST消费者发送HTTP请求
向事件代理表明成功
REST 消费者必须以 200、201、204 或 205 的状态码响应，以表明成功处理消息。任何回复的内容都包含在 HTTP 响应正文中。
向事件代理表明失败
REST 消费者可以使用 4xx 或 5xx 状态码来提供更多关于为什么消息未成功投递的详细信息。REST 消费者必须限制用于错误的 HTTP 状态码，因为对于 4xx 和 5xx 之外的 错误状态码，PubSub+ 事件代理的行为是未定义的。
PubSub+ 事件代理会保留最近被拒绝消息的状态码，类似于没有匹配订阅的丢弃是如何被记录的。日志可以作为与 REST 消费者投递失败相关的调试信息的有用位置。
此外，对于非持久和持久消息，事件代理会根据事件代理上针对任何 4xx 和 5xx 状态码的设置重新尝试投递。每次投递失败都会被捕获在日志中。相应的队列上的最大重试设置控制事件代理进行的重试次数。
队列上的默认最大重试设置是无限（即，消息投递将无限期重试）。因此，建议事件代理管理员为其应用程序指定适当的限制，以避免消息无限期地重新投递给无法处理它们的客户端。
如果消息用尽了重试次数，那么它将遵循常规的保证消息处理，并且会提供统计信息，显示消息是被丢弃还是根据消息标志移动到 DMQ（如果存在）。
当消息投递到远程服务器失败时，远程消费者返回 4xx 或 5xx HTTP 状态码以提供关于为什么消息投递不成功的信息。默认情况下，事件代理将所有 4xx 或 5xx HTTP 状态码解释为投递失败结果，并根据队列的 max-redelivery 和 max-ttl 设置通过 RDP 重新投递消息。
在事件代理版本 10.12.0 及更高版本中，您可以配置一个 HTTP 4xx 和 5xx 状态码列表，事件代理将这些状态码解释为消息拒绝结果而不是投递失败。通常，被拒绝的消息会发送到死信队列（如果已配置），而不会进行任何重试。有关特定消息的负确认（NACK）处理的更多信息，请参阅特定消息的负确认。有关配置 HTTP 状态码以解释为拒绝结果的更多信息，请参阅配置 HTTP 状态码。