> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chaintable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误码

> 识别 OpenAPI、控制台与 SDK 的常见错误，并确定排查方向。

先确认错误来自 HTTP 调用、控制台操作还是 Python SDK。它们使用不同的错误字段，不要只根据一个数字判断原因。

## OpenAPI

OpenAPI 用 HTTP 状态码表示请求结果，并在 JSON 中返回 `code`、`message`、`data`。失败时 `data` 通常为 `null`。

| HTTP 状态 | `code`                | 含义与处理                                |
| ------- | --------------------- | ------------------------------------ |
| 400     | `invalid_argument`    | 请求体或参数格式无效；检查 JSON 和 `parameters` 数组 |
| 401     | `invalid_access_key`  | 缺少或无效的 `AccessKey`；检查请求头及 Key        |
| 403     | `insufficient_units`  | 可用单位不足；核对 Key 所属账户及其 OpenAPI 剩余单位    |
| 404     | `function_not_found`  | 未找到 Function；核对完整 ID                 |
| 429     | `rate_limited`        | 超过账户请求速率；降低并发并延迟重试                   |
| 502     | `function_error`      | 函数加载或执行失败；根据 `message` 在控制台调试        |
| 503     | `service_unavailable` | 服务暂时不可用；间隔后重试                        |
| 504     | `function_timeout`    | 执行超过期限；缩短单次计算或数据访问                   |
| 500     | `internal_error`      | 内部异常；记录请求 ID 并联系支持                   |

请求格式见[接口调用](/zh/guides/openapi/calling)。排查时保留响应的 `X-Request-ID`，不要在问题描述中附带 Access Key。

## 控制台操作

控制台业务错误使用数字错误码和文字信息。常见代码如下：

| 错误码     | 含义            | 处理建议                 |
| ------- | ------------- | -------------------- |
| `40001` | 未登录或会话不可用     | 重新登录后重试              |
| `40002` | 验证码错误         | 核对验证码                |
| `40140` | 账户权限不足        | 检查当前账户与成员角色          |
| `40141` | 邀请不属于当前用户     | 使用被邀请的用户登录           |
| `40200` | 资源额度不足        | 查看 Capacity 和运行实例    |
| `40201` | TODO          | 套餐功能调整后补充含义与处理方式     |
| `40401` | 表参数无效         | 检查字段、表类型和配置          |
| `40420` | 表不存在          | 核对完整表 ID             |
| `40501` | Notebook 参数无效 | 检查代码、参数和计算规格         |
| `40601` | Query 参数无效    | 检查查询配置               |
| `40701` | Function 参数无效 | 检查参数定义和代码            |
| `40801` | 调度参数无效        | 检查 Notebook、模式、时间和规格 |

以 `5` 开头的业务错误通常来自依赖服务。保留完整代码与文字信息：超时、服务不可用、权限不足和参数无效的处理方式不同。

控制台业务错误可能出现在 HTTP 请求成功返回的响应体中，不能只凭浏览器网络面板的 HTTP `200` 判断操作成功。

## Function 和 BlockX

| 错误标识                              | 含义与处理                       |
| --------------------------------- | --------------------------- |
| `CALL_FAILED`                     | 用户函数异常；查看 traceback 和输入参数   |
| `INVALID_ARGUMENT`                | 参数、代码或不允许的导入；核对当前 SDK 与运行限制 |
| `CODE_LOAD_FAILED`                | 函数代码加载失败；检查语法、入口和依赖         |
| `TIMED_OUT` / `DEADLINE_EXCEEDED` | 执行或调用超时；减少工作量               |
| `IO_PROXY_FAILED`                 | 数据访问代理失败；查看具体依赖及是否可重试       |
| `EXECUTOR_LOST`                   | 执行环境中断；保留调用信息并按可重试标记处理      |

`function.call()` 失败时抛出 `FunctionInvokeError`；自定义任务检查 `result.task_result.success`、`failure_code` 和 `retryable`。调试示例见[测试调试](/zh/guides/functions/test-and-debug)。

## BlockDB 与 Leafage

| 错误或异常                                   | 排查方向                               |
| --------------------------------------- | ---------------------------------- |
| `FAILED_PRECONDITION`，共识高度尚未到达          | 检查起始高度、缺失区间和上游进度                   |
| `NOT_FOUND`                             | 检查表、区块或资源是否存在；单条记录缺失也可能正常返回 `None` |
| `PERMISSION_DENIED` / `UNAUTHENTICATED` | 检查运行账户和资源访问环境                      |
| `RESOURCE_EXHAUSTED`                    | 检查资源额度、请求数量或单次数据大小                 |
| `BlockNotFoundError`                    | 检查链 ID 和区块是否可查询                    |
| `ContractCallInvalidInputError`         | 检查地址、方法签名与位置参数                     |
| `ContractExecutionError`                | 合约调用执行失败，检查区块状态和调用条件               |
| `ContractResultDecodeError`             | 返回值无法按声明类型解码，核对输出签名                |
| `ContractCallServiceError`              | 合约查询服务失败，保留错误信息并判断是否重试             |

确定性的参数和代码错误应先修正，再重试。异步写入应按[查看异步写任务](/zh/guides/tables/advanced#查看异步写任务)检查最终状态，不能把提交成功当成最终写入成功。