# 错误与状态码

定位请求失败的原因，判断应修正请求、等待还是重试。

规范链接： https://flashdata.dev/zh/docs/errors
FlashData 核查于 2026-11-04

<a id="status-codes"></a>

## HTTP 状态码

先检查 HTTP 状态，再读取错误码和消息以确定具体原因。

| 状态 | 含义 | 处理方法 |
| --- | --- | --- |
| 400 | 无效请求 | 修正来源、必填字段、参数类型或响应请求头后再重试。 |
| 401 | 认证失败 | 检查 X-API-Key。更换已过期或撤销的密钥；重试相同密钥无效。 |
| 402 | 额度不足 | 检查账户余额。补充额度或由账户所有者解决访问问题后再提交。 |
| 403 | 无权访问 | 检查密钥的来源权限，以及账户或订阅状态。 |
| 404 | 未找到 | 检查 URL、任务 ID 和账户。无权访问的账户或来源任务也可能返回 404。 |
| 406 | 不支持的响应类型 | 使用 Accept: application/json 或 text/plain。通过 X-Respond-With: markdown 选择 Markdown。 |
| 409 | 结果未就绪 / 冲突 | 读取结果时，轮询已有任务直至完成。其他端点则按响应体说明解决冲突。 |
| 410 | 结果已过期 | 使用已保存副本。重试结果 URL 无法恢复过期结果。 |
| 422 | 无效输入 / 任务失败 | 修正报告的字段。读取结果时检查 job.error：失败任务没有成功结果可供获取。 |
| 429 | 达到限制 | 按 Retry-After 或 retry_after 等待。降低请求速率；待处理队列已满时等待已有任务完成。 |
| 500 / 502 / 503 / 504 | 服务或上游故障 | 读取请求可有限退避重试。对于 POST 或提交超时，先检查任务是否已被接受，再决定是否重发。 |

- [检查 API Key](https://flashdata.dev/app/api-keys)
- [额度与定价](https://flashdata.dev/zh/docs/guides/credits-and-billing/reference.md)
- [速率限制](https://flashdata.dev/zh/docs/guides/usage-and-limits/reference.md)

<a id="response"></a>

## 读取错误响应

即使请求纯文本，API 错误也使用 JSON。不同端点的响应体有所不同。按 HTTP 状态及存在时的 code 处理逻辑，用 message 或 detail 解释问题。

### 查询 API

查询错误通常包含 error 和 message；code 为可选字段。认证错误可能使用 success: false，而非 error: true。

#### 400 · application/json

```json
{
  "error": true,
  "code": "unsupported_representation",
  "message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}
```


### 管理 API

V2 问题响应使用 application/problem+json。保留 requestId 供支持人员排查。验证错误还可能包含 fieldErrors，其中有 field、code 和 message。

#### 401 · application/problem+json

```json
{
  "type": "https://api.flashdata.dev/problems/invalid_api_key",
  "title": "Invalid API Key",
  "status": 401,
  "code": "invalid_api_key",
  "requestId": "example-request-id",
  "detail": "The API Key is invalid or unavailable."
}
```



<a id="diagnostics"></a>

## 检查状态、响应头和响应体

使用 curl --include 查看这三项。以下示例通过免费账户读取检查密钥，不会提交查询。请先在环境中设置 FLASHDATA_API_KEY。

### 检查响应 · cURL / Bash

```bash
curl --include --silent --show-error --max-time 20 \
  'https://api.flashdata.dev/v2/api-access/identity' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [认证配置](https://flashdata.dev/zh/docs/guides/headers-and-authentication/reference.md)
- [按症状排查](https://flashdata.dev/zh/docs/guides/troubleshooting/reference.md)

<a id="retries"></a>

## 何时重试

重复 POST 可能创建另一笔计费查询。网络超时不代表第一次请求已被拒绝。收到任务 ID 后立即保存。

| 情形 | 下一步 |
| --- | --- |
| 输入、密钥、权限或余额问题 | 停止。修正请求或账户状态后再重试，不要循环请求。 |
| 429 带等待提示 | 遵循 Retry-After（秒数或 HTTP 日期），或 JSON 中以秒为单位的 retry_after。两者都有时取较长等待时间。 |
| 读取请求：429 / 临时 5xx / 网络错误 | 重试相同 GET。没有等待提示时使用递增延时和随机抖动，并设置最大尝试次数及时间限制。 |
| POST 超时或结果不明确的 5xx | 保留已有任务 ID 并检查状态。没有收到 ID 时，先查看任务历史，再决定是否重新提交。 |

- [任务历史](https://flashdata.dev/app/jobs)
- [恢复智能体任务](https://flashdata.dev/zh/docs/guides/agent-recovery/reference.md)

<a id="job-status"></a>

## 检查后台任务

状态端点返回 HTTP 200 只代表读取成功。检查 job.status 才能确认任务结果。将 JOB_ID 设为已有任务；此命令不会提交替代任务。

| job.status | 处理方法 |
| --- | --- |
| pending / processing | 等待后轮询相同任务。完成前读取结果会返回 409。 |
| completed | 获取并保存结果。原始 JSON 结果返回 302 存储跳转；格式化结果直接返回响应体。 |
| failed | 停止轮询并检查 job.error。失败任务的结果端点返回 422，错误码为 result_not_ready。 |

### 读取任务状态 · cURL / Bash

```bash
curl --fail-with-body --silent --show-error --max-time 30 \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [检查状态 · Python 与 cURL](https://flashdata.dev/zh/docs/reference/realtime-and-async/reference.md#status)
- [获取已完成结果](https://flashdata.dev/zh/docs/reference/realtime-and-async/reference.md#results)
- [Bulk 任务进度](https://flashdata.dev/zh/docs/reference/bulk-processing/reference.md#getBulkJob)

<a id="response-formats"></a>

## 响应格式错误

| 状态 / 错误码 | 修正方法 |
| --- | --- |
| 400 · unsupported_representation | 将 X-Respond-With 设为 markdown，或移除该请求头。 |
| 406 · not_acceptable | 将 Accept 设为 application/json 或 text/plain；指定字符集时使用 UTF-8。 |

- [请求与响应格式示例](https://flashdata.dev/zh/docs/guides/response-formats/reference.md)

<a id="support"></a>

## 请求协助

提供端点、UTC 时间、HTTP 状态、错误码及请求或任务 ID。报告中请移除 API Key、令牌和签名 URL。

- [联系支持](https://flashdata.dev/zh/contact)
