SQL API 使用 HTTP 状态码报告错误。SQL 服务返回的错误通常具有包含对客户安全描述的 text/plain 正文。API 网关拒绝的身份验证错误使用标准 Cloudflare API JSON 响应信封。
| 状态 | 含义 | 操作 |
|---|---|---|
400 |
请求格式错误，或 API 网关拒绝了缺失或无效的身份验证凭据。 | 重试前更正请求或身份验证标头。 |
403 |
身份验证或授权失败，包括显式选择的字段被拒绝。 | 验证令牌权限、资源范围、套餐和所请求的字段。 |
422 |
请求或 SQL 语句无效或不支持。 | 使用 SQL 语言参考 更正请求。 |
429 |
请求超出速率、并发、队列、策略或查询资源限制。 | 重试前等待或降低查询成本。存在 Retry-After 时请遵守该值。 |
500 |
发生意外内部错误。 | 稍后重试。如果错误持续，请联系 Cloudflare Support。 |
501 |
所请求的 SQL 处理行为未实现。 | 移除不支持的语法。 |
503 |
授权、租户解析、排队或数据存储不可用。 | 验证资源标识符，然后对瞬时失败使用有界指数退避和抖动重试。 |
507 |
数据存储无法在其资源限制内完成查询。 | 缩小时间范围、所选数据或结果大小。 |
HTTP 422 响应以 Input was invalid: 开头，并描述验证失败。常见原因包括：
- 对于 HTTP API 请求，SQL 和请求正文中都缺少账户或 zone 范围。Workers 绑定 会自动提供范围，并拒绝 SQL 租户谓词。
- SQL 和
time_range中都缺少下限时间戳边界。 - 在 SQL 和对应请求字段中同时提供租户或时间边界。
- 使用裸数据集名称而不是带 schema 限定的名称。
- 未知或不可用的字段。
- 没有
LIMIT的ORDER BY，Workers Analytics Engine 数据集除外。 - 多条 SQL 语句。
- 缺失、重复或冲突的参数值。
- 所选后端不支持的 SQL 子句、输出格式或函数。
内省端点 返回与查询执行相同的状态码，但其 422 原因与内省参数相关，而非 SQL 语法。特定于内省的原因请参阅错误。
仅当重复查询对应用程序安全时，才重试 429、500、503 和 507 响应。使用带抖动的有界指数退避。如果 429 响应包含 Retry-After，请在该间隔过去之前不要重试。对于 Unable to authorize 或 Unable to resolve account information，首先验证账户或 zone 标识符是否正确。如果在有界重试后错误仍然存在，请联系 Cloudflare Support。
在不更改凭据、权限或查询的情况下，请勿重试 400、403、422 或 501 响应。