响应码与错误

X API 提供以下响应与错误代码，帮助你即时理解并进行调试。有关更多上下文，请参考下方的调试指南与错误索引。

成功响应以 200 系列 HTTP 状态码表示，并返回基于 JSON 的有效负载，其中包含所请求、已创建、已修改或已删除的对象，以及服务器对你请求的解释。

错误响应会返回非 200 系列的 HTTP 状态码。不同的错误码表示不同的错误原因。X API 会尽量为每个请求返回适当的 HTTP status codes。

​

X API v2 HTTP 状态码

Code	Text	Description	Troubleshooting tips
200	OK	请求成功。
400	Bad Request	请求无效或无法处理。随附的错误信息将进一步说明原因。缺少身份验证或包含无效 query 参数的请求被视为无效，并会返回此响应。	请仔细检查你的 JSON 查询格式。例如，如果规则中包含用于精确匹配或其他运算符的双引号字符，你可能需要使用反斜杠进行转义，以将其与 JSON 结构区分开来。
401	Unauthorized	请求的身份验证出现问题。这可能由于缺少或不正确的身份验证凭据所致。在其他未定义情形下也可能返回此状态。	检查你使用的是否为正确的身份验证方法，并确认凭据无误。
403	Forbidden	服务器理解该请求，但已拒绝或不允许访问。随附的错误信息将解释原因。	检查你的开发者账户是否具备所用 endpoint 的访问权限。你可能还需要将 App 加入允许列表（例如 Engagement API 或 X Ads API），或申请相应访问权限。
404	Not Found	请求的 URI 无效，或请求的资源（如某个用户）不存在。	检查你是否使用了有效参数以及该 endpoint 的正确 URI。
409	Connection Exception	当尝试连接到没有规则的过滤的流时返回。	确认你在要连接的 stream 上至少创建了一条规则。过滤的流只会返回与活动规则匹配的 Posts；如果没有规则，stream 将不会返回任何 Posts。
429	Too Many Requests	当由于 App 的请求速率限制或Post 上限已耗尽而无法处理请求时返回。参见请求速率限制。	检查所用 endpoint 在给定时间窗口内允许的请求数。等待窗口重置。将请求错峰/分散以避免触及请求速率限制，或升级到更高的数据套餐。
500	Internal Server Error	出现故障。通常是临时错误，例如高负载情况下或某个 endpoint 暂时出现问题。	查看 X API 的状态页面或开发者社区论坛，了解是否有他人遇到类似问题，或稍后重试。
501	Unimplemented	X API 不支持此 endpoint，无法完成请求。
503	Service Unavailable	X 服务器可用，但请求过载。请稍后再试。	查看 X API 的状态页面或开发者社区论坛，了解是否有他人遇到类似问题，或稍后重试。

当请求发生错误时，响应正文会返回该错误的详细信息，以帮助诊断问题。type 字段（为一个 URI）指示问题的性质，其他字段则提供更多细节。这些响应体中始终会包含 type、title 和 detail 字段（见下表）。其他字段（如下例所示）将根据错误类型而变化。

{
  "client_id": "101010101",
  "required_enrollment": "Standard Basic",
  "registration_url": "https://developer.twitter.com/en/account",
  "title": "客户端禁止访问",
  "detail": "此请求必须由已获批准并已加入所请求 endpoint 的开发者账户发起。请访问我们的文档以了解更多信息。",
  "reason": "client-not-enrolled"
  "type": "https://api.x.com/2/problems/client-forbidden"
}

​

部分错误

在某些情况下，你可能会在返回 200 状态码的响应中看到上述错误。在这些情况下，endpoint 会在尽可能返回可用 data 的同时，提供关于无法返回内容的详细错误信息。

例如，Posts 查找 endpoint 允许 X 的开发者 App 请求多个 id。如果其中部分 Post 可用，但有一个已被删除，那么可用的 Posts 会在响应的 data 字段中返回。负载中还会返回一个额外的 errors 字段，指明哪些请求的 Post 无法返回。其格式与完整请求错误相同，便于排查问题。

​

错误信息

每种问题类型都指明所遇问题的性质。你可能会遇到的问题完整列表也可在我们的 API 规范 中查看。

X API 会尽量为每个请求返回合适的 HTTP 状态码。

标题	类型	描述
通用问题	about:blank	通用问题；除 HTTP 状态码提供的信息外，没有其他附加信息。
无效请求问题	https://api.X.com/2/problems/invalid-request	表示该请求无效的问题。如果请求包含 POST 请求体，请确保内容是有效的 JSON 并符合 OpenAPI 规范。
资源未找到问题	https://api.X.com/2/problems/resource-not-found	表示指定的 Post、User 等不存在的问题。
资源未授权问题	https://api.X.com/2/problems/not-authorized-for-resource	表示你无权查看特定 Post、User 等的问题。
客户端被禁止问题	https://api.X.com/2/problems/client-forbidden	表示你的客户端被禁止发出此请求的问题。
不允许的资源问题	https://api.X.com/2/problems/disallowed-resource	表示所请求的资源违反本 API 原则的问题。
不支持的身份验证问题	https://api.X.com/2/problems/unsupported-authentication	表示所使用的身份验证方式不受支持的问题。
使用上限问题	https://api.X.com/2/problems/usage-capped	表示已超出使用配额上限的问题。
连接异常问题	https://api.X.com/2/problems/streaming-connection	表示连接出现异常的问题。
客户端已断开问题	https://api.X.com/2/problems/client-disconnected	你的客户端已断开连接。
运维断开问题	https://api.X.com/2/problems/operational-disconnect	因运维原因你已被断开连接。
规则数量上限问题	https://api.X.com/2/problems/rule-cap	你已超出规则的最大数量。
规则长度问题	https://api.X.com/2/problems/rule-length	根据你的访问级别，你已超出 query（查询）或规则允许的最大字符数。参见访问级别。
无效规则问题	https://api.X.com/2/problems/invalid-rules	你提交的规则无效。
重复规则问题	https://api.X.com/2/problems/duplicate-rules	你提交的规则重复。

​

故障排查提示

调试代码

在构建应用时，偶尔遇到错误或异常问题是正常的。以下是一些调试代码的建议：

首先将问题拆解为更小的部分，以定位故障点。比如，如果你正在集成 REST 或 streaming endpoint，问题可能出在以下任一项：

• 该 endpoint 需要正确的身份验证。
• 该 endpoint 需要有效的参数和请求头。任何过滤规则都应使用正确的运算符和合适的语法构建。
• 该 endpoint 的 URI 必须正确；对于 REST endpoint，还必须使用正确的 HTTP 方法。
• 你尝试访问的 data 或资源对你不可用（例如，私有 data 仅对已通过身份验证的用户可用）。
• 你当前的数据套餐仅允许访问特定 endpoint，并受特定的请求速率限制。请查看你的开发者门户以了解更多详情。
• 你的代码使用了第三方库来集成该 endpoint。
• 你的代码需要能够成功解析该 endpoint 的响应。

阅读随附的错误消息，这通常能较好地指示问题所在。请参阅错误与响应代码部分中的表格，获取针对各个错误代码的故障排查建议。

对于 REST endpoint，你可以使用 Postman 或 Insomnia 等 REST 客户端验证上述步骤 (1) 至 (5)（参阅我们的“Postman 入门”指南）。如果使用 REST 客户端的请求返回 200 成功状态码，则可认为问题出在你的代码或所用库上，而非 endpoint 请求本身。

对于 streaming endpoint，你可以使用 cURL（一个使用 URL 语法来获取或发送请求的命令行工具）检查问题是出在对 endpoint 的请求（上述步骤 (1) 至 (5)），还是出在你的代码本身（上述步骤 (6) 至 (7)）。

身份验证问题

• 检查你是否使用了该 endpoint 要求的正确身份验证方法。可在该 endpoint 的 API 参考页面确认。
• 检查你的身份验证凭据是否正确。你可以在开发者控制台的 Apps 区域（“Details”下）查看或重新生成你的 App 密钥和令牌。
• 检查你是否已为请求正确授权 OAuth 1.0a 请求，并包含 oauth_nonce、oauth_signature 和 oauth_timestamp。
• 如果问题仍然存在，考虑使用 OAuth 库、Postman、Insomnia 等 REST 客户端，或使用 xurl。

查看我们的身份验证指南以获取上述内容的更多信息。

请求速率限制与 Post 上限问题

当你触及某个 endpoint 的请求速率限制，或触及 Post 上限时，可能会返回 429 错误。

如果返回特定的“Too many requests”错误，表示你触及了该 endpoint 的请求速率限制。换言之，你已超过该 endpoint 在指定时间段内允许的最大请求数。

请注意，请求速率限制按 App 级别和用户级别分别设定。

• X App 级别表示在使用 OAuth 2.0 App-Only 时允许的请求数量，此时请求速率限制在整个 App 维度上全局确定。例如，如果某方法允许每个请求速率限制窗口发起 15 个请求，那么它允许你代表你的 X App 在每个窗口内发起 15 个请求。此限制与用户级别限制完全分开计算。请参阅我们的OAuth 2.0 App-Only指南了解更多。
• 用户上下文级别表示在使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码模式（Authorization Code）配合 PKCE 时，每个用户 Access Token 可发起的请求数量。例如，如果某方法允许每个请求速率限制窗口发起 15 个请求，那么它允许每个窗口、每个用户 Access Token 发起 15 个请求。请阅读我们的指南，了解如何通过 OAuth 1.0a 和 OAuth 2.0 获取用户的 Access Tokens。

首先检查你正在使用的 endpoint 的请求速率限制。你可以在该 endpoint 的 API 参考页面以及新的开发者门户仪表板中找到此信息。

查看我们的文档以获取有关请求速率限制的更多信息，包括如何使用 HTTP 头来跟踪你的 App 在特定请求速率限制窗口中的使用情况、如何从 429 请求速率限制错误中恢复，以及如何避免首先触发请求速率限制的技巧：

• v2 endpoints 的请求速率限制

如果你收到了特定的“Usage cap exceeded: Monthly product cap”错误，这意味着你触及了当前访问级别的 Post 上限。我们在文档页面上对这些Post 上限提供了详尽说明。

缺失 Post 问题

如果你预期某个 Post 会被返回，但该 endpoint 未返回它，请按以下步骤操作。

• 检查你的规则，确保你使用了正确的operators和syntax。将规则拆分为更小的子句，以确保语法正确。
• 如果发送该 Post 的账号在创建 Post 时处于受保护状态，则该 Post 不会被返回——即使在向 endpoint 发起请求时该账号已为公开。你通常可以使用X 高级搜索进行检查：如果通过 X 高级搜索功能无法检索到某个 Post，你应当假定该 endpoint 也不会返回它。

以下步骤仅适用于 stream 类 endpoint：

• 当该 Post 发送时，你是否已连接到 stream？请记住，Post 对象中提供的时间戳为 UTC 时间。如果在该 Post 发送时发生了断开，请查看用于回填任何遗漏 data 的恢复与冗余功能。
• 当该 Post 发送时，你的规则是否已生效？请记住，Post 对象中提供的时间戳为 UTC 时间。

缓冲区已满导致的断开问题

当你的 stream 无法跟上我们投递 data 的速度，且你的 App 未能足够快地从 stream 消费 data 时，你可能会遇到以下错误之一：

This stream has been disconnected because your client was unable to keep up with us.

This stream has been disconnected for operational reasons.

我们允许在一段时间内出现一定的投递滞后，并在我们端为每个 stream 提供临时的分段缓冲区；但如果你仍未追上，我们会发起断开，以便你在当前时间点重新连接。请注意，这可能会导致 data 丢失（对于在缓冲区已满断开时仍位于缓冲区中的 data）。

这些情况可能发生在数据量大幅激增时。一般而言，我们建议将快速消费 data 的缓冲消费流程与后续处理流程分离。

如果你是使用 v1.1 endpoint 的 Enterprise 客户，可在我们的文章中了解如何优化你的 App 以防止此类断开，参见关于连接的说明，以及关于消费流式数据的文章此处和此处。

有多种工具可用于在断开后检索遗漏的 Post，包括下列工具。请注意，以下工具仅适用于 Enterprise 级别访问的 v1.1 endpoint。

• Redundant Connections - 通过多路连接，从多个服务器消费 stream，以在其中一路断开时防止 data 丢失。
• Replay - 使用独立的 stream 在最近 5 天内恢复 data。
• Backfill - 在 5 分钟内重新连接并从中断处继续。
• Historical PowerTrack - 从整个 X 归档中恢复 data。

​

获取帮助

X 社区论坛欢迎你就 X 开发者平台提出技术问题。该讨论区汇集了其他开发者的提问，以及与使用 X API 相关的各类技术主题与信息。

我们鼓励你通过回答问题并在我们的论坛参与讨论来加入交流。X 员工也会在此提供支持。

X 社区论坛

​

在发布问题之前

• 在 X 开发者文档中查找与你的问题相关的信息
• 在社区论坛中查找其他开发者提出的类似问题
• 查看社区论坛使用指南

​

发布问题时，请务必包含以下信息

• 问题描述
• 发起的 API 调用（如有可能，请包含请求头）
• 返回的 X 响应（包括任何错误信息）
• 你期望得到的结果
• 为排查问题已执行的步骤列表
• 复现该问题所需的步骤列表
• 如适用，问题发生的时间范围
• 如适用，App ID、Post ID 等
• 相关的代码示例或截图

请确保每个帖子仅包含一个主题/问题。

如果你有功能需求或反馈，请通过 X Developer Platform Feedback Form 提交。

对于与政策相关的问题（例如 App 被暂停），请联系 Policy support。

对于与 X 相关的问题（例如登录和账户支持），请使用 X Help Desk。