跳转到正文
中文
获取 API 密钥
浏览文档

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."
}

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

使用 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。