跳转到主要内容
X API 提供以下响应与错误代码，便于即时理解与排查。可参阅下方的调试指南与错误索引以获取更多上下文。 成功响应以 200 系列 HTTP 状态码表示，且包含基于 JSON 的负载，其中包括所请求、创建、修改或删除的对象，以及服务器对你的请求的理解与解释。 错误响应将返回非 200 系列的 HTTP 状态码。不同的错误码表示不同的错误原因。X API 会尽力为每个请求返回适当的 HTTP 状态码。

​
X API v2 HTTP 状态码

CodeTextDescriptionTroubleshooting tips
200OK请求成功。
400Bad Request请求无效或无法处理。随附的错误消息会进一步说明。未进行认证或包含无效查询参数的请求被视为无效，并将返回此响应。请仔细检查你的 JSON 查询格式。例如，如果规则中包含用于精确匹配或其他运算符的双引号字符，你可能需要使用反斜杠进行转义，以便将其与 JSON 结构本身区分开。
401Unauthorized对你的请求进行认证时出现问题。这可能是由于缺失或不正确的认证凭证。在其他未定义的情况下也可能返回此状态。检查你是否使用了正确的认证方法，并确保你的凭证无误。
403Forbidden请求已被理解，但被拒绝或不允许访问。随附的错误消息会解释原因。检查你的开发者账号是否包含你正在尝试使用的端点的访问权限。你可能还需要将你的应用加入允许名单（例如 Engagement API 或 Ads API），或注册以获取访问权限。
404Not Found请求的 URI 无效，或所请求的资源（例如用户）不存在。检查你是否使用了有效的参数，以及与你正在使用的端点相对应的正确 URI。
409Connection Exception当尝试连接到没有规则的过滤流时返回。检查你是否在要连接的流上至少创建了一条规则。过滤流只会返回与活动规则匹配的 Post。若没有任何规则，流将不会返回任何 Post。
429Too Many Requests由于应用的速率限制或Post 上限已耗尽而无法处理请求时返回。参见速率限制。检查你所用端点在每个时间窗口允许的请求数。等待该时间窗口重置。拉开请求间隔以避免触发速率限制，或升级到下一个可用的数据方案。
500Internal Server Error出现问题。通常为暂时性错误，例如高负载情况下或某个端点暂时出现故障。查看 X API 的状态页面或开发者社区论坛，以了解是否有他人遇到类似问题，或稍后再试。
501UnimplementedX API 不支持此端点，无法满足该请求。
503Service UnavailableX 服务器正常运行，但请求过载。请稍后重试。查看 X API 的状态页面或开发者社区论坛，以了解是否有他人遇到类似问题，或稍后再试。
当请求发生错误时，响应正文会返回该错误的详细信息，以帮助诊断问题。type 字段为一个 URI，用于指示问题的性质，其他字段提供具体细节。在这些响应正文中将始终返回 type、title 和 detail 字段（见下表）。任何其他字段（如下例所示）将根据错误类型而变化。 
{
  "client_id": "101010101",
  "required_enrollment": "标准基础版",
  "registration_url": "https://developer.twitter.com/zh/account",
  "title": "客户端禁止访问",
  "detail": "此请求必须使用已获批准并已注册所请求端点的开发者账户。请访问我们的文档了解更多信息。",
  "reason": "客户端未注册",
  "type": "https://api.x.com/2/problems/client-forbidden"
}

​
部分错误

在某些情况下，你可能会在返回 200 状态码的响应中看到上述详细的 errors。此时，该端点会尽可能返回可用的 data，同时提供关于无法返回内容的详细错误信息。 例如，Posts 查询端点 允许 X 的开发者应用请求多个 ID。若其中部分 Post 可用，但有一个已被删除，那么可用的 Post 会在响应的 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基于你的访问级别，你的查询或规则已超过允许的最大字符数。参见 访问级别。
无效规则问题https://api.X.com/2/problems/invalid-rules你提交的规则无效。
重复规则问题https://api.X.com/2/problems/duplicate-rules你提交的规则重复。

​
疑难排解提示

在构建应用时，偶尔遇到错误或异常情况是正常的。以下是一些调试代码的建议：先将问题拆解为更小的部分，以定位具体原因。例如，如果你正在集成 REST 或流式端点，问题可能出在以下任一方面：
  • 该端点需要正确的认证。
  • 该端点需要有效的参数和请求头。任何筛选规则都应使用正确的运算符并采用合适的语法构建。
  • 端点的 URI 必须正确；对于 REST 端点，还必须使用正确的 HTTP 方法。
  • 你尝试访问的 data 或资源对你不可用（例如，私有 data 仅对已认证用户可用）。
  • 你当前的数据套餐仅允许访问特定端点，并受特定的速率限制。请查看你的开发者门户了解详情。
  • 你的代码使用了第三方库来集成该端点。
  • 你的代码需要能成功解析端点的响应。
阅读随附的错误消息，这通常能清楚地指示问题所在。参考错误与响应代码部分中的表格，获取对应每个错误代码的排障提示。对于 REST 端点，你可以使用 Postman 或 Insomnia 等 REST 客户端验证上述 (1) 至 (5) 步（参阅我们的“Postman 入门”指南）。如果使用 REST 客户端的请求返回 200 成功状态码，可认为问题出在你的代码或所用库上，而非端点请求本身。对于流式端点，你可以使用 cURL（一个使用 URL 语法发送/获取请求的命令行工具）来检查问题是出在对端点的请求（上述 (1) 至 (5) 步），还是出在你的代码本身（上述 (6) 至 (7) 步）。
  • 检查你是否使用了该端点要求的正确认证方式。可通过该端点的 API 参考页面确认。
  • 检查你的认证凭据是否正确。你可以在开发者门户的应用（Apps）区域（“Details”下）查看或重新生成你的应用密钥和令牌。
  • 检查你是否已使用 oauth_nonce、oauth_signature 和 oauth_timestamp 正确为 OAuth 1.0a 请求授权。
  • 如果问题仍然存在，考虑使用 OAuth 库、Postman 或 Insomnia 等 REST 客户端，或 xurl。
查看我们的认证指南以获取上述各项的更多信息。
当你触及某个端点的速率限制或达到 Post 上限时，可能会返回 429 错误。如果返回特定的“Too many requests”错误，表示你触发了该端点的速率限制。换句话说，你在指定时间段内的请求次数已超过该端点允许的最大值。请注意，速率限制分为按应用和按用户两个层级设定。
  • X 应用层级表示在使用 OAuth 2.0 App-Only 时允许的请求次数，此时速率限制在整个应用范围内全局生效。举例来说，如果某个方法在每个速率限制窗口允许 15 次请求，那么它允许你代表你的 X 应用在每个窗口发出 15 次请求。该限制与用户层级限制完全独立。请阅读我们的OAuth 2.0 App-Only指南了解更多信息。
  • 用户上下文层级表示在使用 OAuth 1.0a 用户上下文或 OAuth 2.0 授权码（PKCE）时，每个用户 Access Token 可进行的请求次数。举例来说，如果某个方法在每个速率限制窗口允许 15 次请求，那么它允许每个窗口、每个用户 Access Token 进行 15 次请求。阅读我们的指南，了解如何通过 OAuth 1.0a 和 OAuth 2.0 获取用户的 Access Token。
首先检查你正在使用的端点的速率限制。你可以在该端点的 API 参考页面以及新版开发者门户仪表板中找到相关信息。查看我们的文档以获取有关速率限制的更多信息，包括如何使用 HTTP 头来跟踪你的应用在特定速率限制窗口中的使用情况、如何从 429 速率限制错误中恢复，以及避免被限流的建议：如果你收到特定的“Usage cap exceeded: Monthly product cap”错误，这意味着你已达到当前访问级别的 Post 上限。我们的文档页面上提供了关于这些 Post 上限 的详细说明。
如果你预期某条 Post 会返回，但端点未返回，请按以下步骤排查。
  • 检查你的规则，确保使用了正确的运算符和语法。将规则拆分为更小的子句以确认语法无误。
  • 如果发送该 Post 的账号在创建时处于受保护状态，则该 Post 不会返回——即使在请求该端点时该账号已设置为公开。你通常可以使用 X 高级搜索进行检查：如果通过 X 高级搜索无法检索到该 Post，则应假定端点也不会返回它。
以下步骤仅适用于流式端点：
  • 发送该 Post 时你是否已连接到流？请记住，Post 对象中的时间戳为 UTC 时间。如果在该 Post 发送时发生断连，请查看用于回填遗漏数据的恢复与冗余功能。
  • 发送该 Post 时你的规则是否已生效？请记住，Post 对象中的时间戳为 UTC 时间。
当你的流无法跟上我们传送数据的速度，且你的应用未能足够快地从流中消费数据时，你可能会遇到以下错误之一：
This stream has been disconnected because your client was unable to keep up with us.

This stream has been disconnected for operational reasons.
我们允许在一段时间内出现延迟传送，并在我们端为每个流提供临时分段缓冲；但如果你仍未赶上，我们会发起断开连接，以便你在当前时间点重新连接。请注意，这可能会导致数据丢失（对于在缓冲区达到上限而断开时仍位于缓冲区中的数据）。这些情况可能发生在数据出现大幅激增时。通常，我们建议将快速消费数据的缓冲消费流程与后续处理流程解耦。如果你是使用 v1.1 端点的企业客户，可在我们的连接文章，以及关于消费流式数据的此处和此处了解如何优化你的应用以防止此类断开。针对因断开而错过的 Post，我们提供多种补救工具，包括以下所列。请注意，以下工具仅适用于企业级访问的 v1.1 端点。
  • 冗余连接 - 通过多路连接从多个服务器消费流，当其中一个断开时避免数据遗漏。
  • 重放 - 使用单独的流恢复过去 5 天内的数据。
  • 回填 - 在 5 分钟内重新连接并从中断处继续。
  • Historical PowerTrack - 从整个 X 存档中恢复数据。

​
获取帮助

X 社区论坛向您开放，欢迎就 X 开发者平台提出技术问题。这里是一个讨论型社区，您可以查阅其他开发者的问题，以及与使用 X API 相关的各类技术信息。 我们鼓励您通过解答问题并参与论坛讨论积极交流。X 员工也会在此提供支持。

​
发布问题前

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

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

  • 问题描述
  • 发起的 API 调用（如可行，请包含请求头 headers）
  • 返回的 X 响应（包括任何错误消息）
  • 你的预期结果
  • 已执行的故障排查步骤列表
  • 复现该问题所需的步骤列表
  • 如适用，问题发生的时间范围
  • 如适用，应用 ID、Post ID 等
  • 相关的代码示例或截图
请确保每个帖子仅包含一个主题/问题。 如有功能请求或反馈，请通过 X Developer Platform 反馈表 提交。 对于与政策相关的问题（例如应用暂停），请联系 政策支持。 对于与 X 相关的问题（例如登录和账户支持），请使用 X 帮助中心。