# 错误码 (/docs/api/native/database/errors)



管理端点返回领域码；两个表端点返回 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

```json
{
  "code": "FIELD_TYPE_IMMUTABLE",
  "message": "field type is immutable",
  "details": null,
  "hint": null
}
```

## 表端点错误体 [#表端点错误体]

响应示例 — HTTP 400

```json
{
  "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 |

```json
{
  "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 的错误示例：

```json
{
  "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，例如：

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