数据库
错误码
Database 错误的状态码、PostgREST code 与重试属性。
管理端点返回领域码；两个表端点返回 PostgREST code。HTTP 状态与重试属性如下。
| 领域码 | HTTP | PostgREST code | 可重试 |
|---|---|---|---|
| SINGULAR_MISMATCH | 406 | PGRST116 | 否 |
| AMBIGUOUS_EMBED | 300 | PGRST201 | 否 |
| EMBED_NOT_FOUND | 400 | PGRST200 | 否 |
| INVALID_PREFERENCE | 400 | PGRST122 | 否 |
| QUERY_CANCELED | 500 | 57014 | 否 |
| RANGE_NOT_SATISFIABLE | 416 | PGRST103 | 否 |
| NOT_ACCEPTABLE | 406 | PGRST107 | 否 |
| OPERATOR_TYPE_MISMATCH | 400 | 42883 | 否 |
| DATABASE_NOT_FOUND | 404 | PGRST125 | 否 |
| TABLE_NOT_FOUND | 404 | PGRST205 | 否 |
| FIELD_NOT_FOUND | 400 | 42703 | 否 |
| VALIDATION_FAILED | 400 | 23514 | 否 |
| UNIQUE_VIOLATION | 409 | 23505 | 否 |
| REFERENCE_RESTRICT | 409 | 23503 | 否 |
| FIELD_TYPE_IMMUTABLE | 400 | — | 否 |
| LIMIT_EXCEEDED | 400 | 54000 | 否 |
| UNSUPPORTED | 400 | PGRST127 | 否 |
| INVALID_PARAMS | 400 | PGRST100 | 否 |
| DATABASE_INVALID_STATE | 409 | — | 否 |
| CAPACITY | 503 | — | 是 |
| NOT_IMPLEMENTED | 501 | PGRST127 | 否 |
可重试不表示重复原请求一定成功。例如 57014 应先缩小查询范围或调整过滤条件，再重试。
管理端点错误体
响应示例 — HTTP 400
{
"code": "FIELD_TYPE_IMMUTABLE",
"message": "field type is immutable",
"details": null,
"hint": null
}表端点错误体
响应示例 — HTTP 400
{
"code": "PGRST127",
"message": "operator fts is not supported",
"details": null,
"hint": null
}code、message、details、hint 四个字段始终存在；details 与 hint 可以为 null。
未开放服务错误体
响应示例 — HTTP 501
| 响应头 | 值 |
|---|---|
| x-should-retry | false |
{
"code": "not_implemented",
"message": "auth is not provided by praxis-database"
}这五个服务直接返回 not_implemented；它与错误表中的领域码 NOT_IMPLEMENTED 不同。
按错误细节修正请求
保留字段名只有 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
}