错误与排错

错误的形态

你永远不必去解析散文。两种传输方式携带的都是同一个机器可读的错误码：

// SDK
const { data, error } = await lingcode.from('todos').update({ done: true });
if (error) {
  console.log(error.code);   // 例如 "where_required"
  console.log(error.status); // 例如 400
}

// REST
// HTTP 400
// { "ok": false, "error": "where_required", "message": "update requires a filter" }

在下面的表里查 error.code。

数据

由表读取、写入和 SQL 查询编辑器抛出。完整指南：数据库。

错误码	含义	修复办法
where_required	update()/delete() 在没有过滤器的情况下运行了。	加一个过滤器（.eq/.match）来限定行范围。
table_not_found (404)	表名写错了，或者该表还没创建。	核对表名；运行创建它的迁移。
invalid_request (400)	缺少必填字段或格式有误（表/过滤器/行结构不对）。	修正表名、过滤器或行结构。
not_provisioned (409)	后端尚未就绪（仍在开通中）。	稍后重试，或轮询后端状态。
read_only_violation	控制台的 SQL 查询编辑器只运行只读语句（SELECT/WITH/TABLE/EXPLAIN/SHOW）。	写入和 DDL 请走迁移。
quota_exceeded (402)	触及了套餐上限（表数、行数等）。	腾出空间或升级。

认证

由注册、登录、OTP/魔法链接、MFA 和 OAuth 抛出。完整指南：认证。

错误码	含义	修复办法
unauthorized (401)	缺少或无效的令牌。	发送匿名密钥（Bearer 或 ?apikey=）或已登录的用户令牌。
forbidden (403)	RLS 策略拒绝了它——该行不属于此用户，或该表没有授予访问权限的策略。	检查你的策略。
invalid_code / invalid_or_expired / too_many_attempts	一次性验证码或魔法链接错误、过期，或重试过于频繁。	重新申请一个。
mfa_required	后端要求 MFA，而当前会话尚未达到 AAL2。	完成 MFA 验证步骤。
state_secret_missing / invalid_redirect	OAuth 未完全配置，或重定向 URL 不在允许列表中。	在控制台配置提供方，并使用允许的重定向地址。

存储

由存储桶的上传、下载和删除抛出。完整指南：存储。

错误码	含义	修复办法
object_not_found (404)	该存储桶/路径下没有对象。	核对存储桶和路径。
object_too_large / value_too_large	文件超过了单对象内联上传上限。	改用预签名直传路径（SDK 会自动处理）或升级套餐。
direct_upload_unavailable	该后端不支持预签名直传对象存储的路径。	对小文件回退到内联上传。
quota_exceeded (402)	后端的总存储上限已达到。	腾出空间或升级。

函数

由内置和自定义无服务器函数调用抛出。完整指南：函数。

错误码	含义	修复办法
unknown_function (404)	slug 写错了——是名字不对，而不是函数功能不可用。	核对函数 slug。
functions_runtime_unavailable (503)	该服务器未安装 Deno 运行时，因此自定义函数无法运行（内置函数仍可用）。	改用内置函数，或联系运维安装运行时。
function_error	你的函数抛出了异常。	查看返回的 logs 字段获取错误信息。
source_too_large	自定义函数源码超过 256 KB。	精简代码。
missing_secret	函数需要一个未设置的保险库密钥。	在控制台密钥里添加它。
timeout	函数超过了套餐的墙钟时间限制（free 3s / pro 10s / max_pro 30s）。message：Function timed out after Xms。	让它更快，或把耗时工作挪到别处。

密钥

由密钥保险库抛出。完整指南：密钥保险库。

错误码	含义	修复办法
too_many_secrets	一个后端最多允许 32 个密钥。	先删除一个未使用的密钥。
value_too_large	密钥值超过 16 KB。	存一个更短的值，或存一个指向数据的引用。
vault_not_configured	服务器的保险库密钥未设置（运维/基础设施问题，不是你的应用问题）。	联系运维。

托管与部署

由应用部署和自定义域名绑定抛出。完整指南：应用托管。

错误码	含义	修复办法
no_build_config	构建没有产出 dist/server/wrangler.json（Cloudflare Vite 插件没有运行）。	用正确的适配器重新构建。
bundle_too_large	Worker 打包产物超过 60 MB。	精简依赖和资源文件。
cap_reached	你已达到托管 Worker 应用数量上限（10 个）。	删除一个旧的或升级。
rate_limited	部署过于频繁（每小时 12 次）。	稍后重试。
custom_domain_failed / domain_taken / reserved_domain / invalid_domain	自定义域名绑定问题——DNS 未指向边缘节点、域名已绑定到别处、被保留，或格式有误。	把 DNS 指向边缘节点，释放或改名域名，并使用合法的主机名。

向量检索

由语义检索抛出。完整指南：向量检索。

错误码	含义	修复办法
embeddings_not_configured / embeddings_failed	托管向量化不可用或失败。	把它配置好，或向 vector.search 传入你自己预先计算好的向量。

通用

任何端点都可能返回的临时性和限流错误。

错误码	含义	修复办法
server_error / cloud_error	临时性服务器问题。	重试；若持续出现，联系支持。
too_many_inflight	同时进行的并发请求过多。	退避后重试。
rate_limited	你发送请求的速度太快。	放慢速度。