浏览文档
API 参考
定位请求失败的原因,判断应修正请求、等待还是重试。
本页内容
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 错误也使用 JSON。不同端点的响应体有所不同。按 HTTP 状态及存在时的 code 处理逻辑,用 message 或 detail 解释问题。
查询错误通常包含 error 和 message;code 为可选字段。认证错误可能使用 success: false,而非 error: true。
400 · application/json
{
"error": true,
"code": "unsupported_representation",
"message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}V2 问题响应使用 application/problem+json。保留 requestId 供支持人员排查。验证错误还可能包含 fieldErrors,其中有 field、code 和 message。
401 · application/problem+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."
}检查状态、响应头和响应体
使用 curl --include 查看这三项。以下示例通过免费账户读取检查密钥,不会提交查询。请先在环境中设置 FLASHDATA_API_KEY。
检查响应 · cURL / 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'何时重试
重复 POST 可能创建另一笔计费查询。网络超时不代表第一次请求已被拒绝。收到任务 ID 后立即保存。
| 情形 | 下一步 |
|---|---|
| 输入、密钥、权限或余额问题 | 停止。修正请求或账户状态后再重试,不要循环请求。 |
| 429 带等待提示 | 遵循 Retry-After(秒数或 HTTP 日期),或 JSON 中以秒为单位的 retry_after。两者都有时取较长等待时间。 |
| 读取请求:429 / 临时 5xx / 网络错误 | 重试相同 GET。没有等待提示时使用递增延时和随机抖动,并设置最大尝试次数及时间限制。 |
| POST 超时或结果不明确的 5xx | 保留已有任务 ID 并检查状态。没有收到 ID 时,先查看任务历史,再决定是否重新提交。 |
检查后台任务
状态端点返回 HTTP 200 只代表读取成功。检查 job.status 才能确认任务结果。将 JOB_ID 设为已有任务;此命令不会提交替代任务。
| job.status | 处理方法 |
|---|---|
| pending / processing | 等待后轮询相同任务。完成前读取结果会返回 409。 |
| completed | 获取并保存结果。原始 JSON 结果返回 302 存储跳转;格式化结果直接返回响应体。 |
| failed | 停止轮询并检查 job.error。失败任务的结果端点返回 422,错误码为 result_not_ready。 |
读取任务状态 · cURL / 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'响应格式错误
| 状态 / 错误码 | 修正方法 |
|---|---|
| 400 · unsupported_representation | 将 X-Respond-With 设为 markdown,或移除该请求头。 |
| 406 · not_acceptable | 将 Accept 设为 application/json 或 text/plain;指定字符集时使用 UTF-8。 |
请求协助
提供端点、UTC 时间、HTTP 状态、错误码及请求或任务 ID。报告中请移除 API Key、令牌和签名 URL。