> This page is for 平台, version 旧版.
> For other versions, use one of these documentation indexes:
> - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt
> - V4 实验版: https://next.developer.frame.io/platform/v4-experimental/llms.txt
> - 旧版: https://next.developer.frame.io/platform/v2/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://next.developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server.

# API 错误代码

Frame.io API 可能返回以下常见错误：




| 代码 | 详情 | 原因 |
| ---------- | ---------- | ---------- |
| `401` | **未授权** -- API 令牌无效。请检查以确保您使用的是“持有者令牌”身份验证方式，并通过 Authorization 标头传递您的令牌。 |  |
| `402` | **用量超出限制** -- 您已超出 Frame.io 计划限制。 |  |
| `403` | **禁止访问** -- 您无权访问该资源。此代码既会因用户访问权限不足而返回，也会因令牌权限范围不足而返回。 |  |
| `404` | **未找到** -- 未找到资源。 | 资源已被移动或删除。 |
| `422` | **无效参数** -- 提供的一个或多个参数无效。 |  |
| `429` | **速率受限** -- 您已达到 API 的速率限制。 |  |
| `500` | **服务器错误** -- 我们的服务器无法解析您的请求，或者无法在可用时间范围内（30 秒）完成您的请求。 | 请求 URL 或请求体格式错误，或因其他某些原因无法完成请求。 |




# 故障诊断常见错误

当使用有效的 API 令牌执行常见任务时，最常见的错误是 `403`、`404` 和 `500`。**403** 错误通常表示以下三种情况之一：
1. 请求中使用的令牌，和/或该令牌所属的用户对请求资源所在的 Frame.io 帐户区域没有足够的访问权限。
2. 该令牌对所请求的资源没有足够的 [权限范围]()。例如：在没有 `comments.read` 权限范围的情况下调用 `GET /comments/`。
3. 网络流量问题正在阻止 Frame.io API 处理该请求。*如果您怀疑您的请求因网络流量问题而被阻止，请联系客户支持。*

**404** 错误通常表示资源不再存在 -- 它已被移动或删除。**500** 错误通常表示请求 URL 或请求体格式有误，但当我们无法在可用时间范围内（30 秒）完成请求时也可能发生这种情况。

# 速率限制

Frame.io API 对每个令牌都应用速率限制。令牌的默认限制为每秒 50 次调用。某些方法的限制更低（例如 POST `/assets/:id/children` 的速率限制为每秒 5 个资产）。

所有限制均可能发生变化，当达到限制时，将返回 429 HTTP 错误。我们建议使用指数退避方法来处理速率限制。

请查看[我们的指南](./rate-limits)以了解更多关于速率限制的信息。