限制与错误

按以下边界规划库与查询。

单条请求最长执行 8 秒，超时返回 57014（重试不会成功）；给过滤和排序字段建索引，或缩小查询范围。不带过滤的计数总是很快。不指定 limit 时每次最多返回 1000 行，用 limit / offset 或 Range 翻页。大表上需要批量修改或删除时，按主键或索引字段的范围分批执行，例如每批几万行。单次批量插入可包含上述行数上限，不必将每行的字段数相乘作为查询参数数目。

错误码与重试属性 → 一次批量 POST 最多插入 500 行，单次请求是原子的：任何一行失败，整批回滚。跨请求没有事务；需要一起成功的行应放在一次批量 POST 中。有关联依赖时先查后插，并处理并发变化导致的关联错误。

同一批次按所有行的键的并集补齐缺失值为 null（PostgREST 行为）。发送 Prefer: missing=default 可改用字段默认值；显式 null 仍为 null，没有默认值的必填字段仍必须提供。默认 return=minimal 返回 201、body 为空；发送 Prefer: return=representation 才返回行。

按错误细节修正请求

保留字段名只有 id；新字段名不能以 _ 开头，这个前缀留给系统元数据。created_at、updated_at、version 可用作普通字段名。datetime 字段可用 "now()" 作为默认值。

details 指出字段或 JSON 路径及实际收到的值，批量校验还包含从 0 开始的行号。值最多显示 80 个字符，不回显整行。hint 给出修正方式，没有建议时为 null。下面是省略第 2 行必填 title 的错误示例：

{
  "code": "23514",
  "message": "row validation failed",
  "details": "row 1: title: required value (got null)",
  "hint": "Rows in one insert are filled to the union of their keys with null (PostgREST behavior). Send every key in every row, or send Prefer: missing=default to use field defaults."
}

唯一冲突返回 409，例如：

{
  "code": "23505",
  "message": "unique constraint violated",
  "details": "Key (email)=(a@b.c) already exists.",
  "hint": null
}