+
+ +
+

错误

+

PostgREST 错误消息遵循 PostgreSQL 错误结构。它包括 MESSAGE、DETAIL、HINT、ERRCODE，并将向响应添加 HTTP 状态码。

+
+

来自 PostgreSQL 的错误

+

PostgREST 将转发来自 PostgreSQL 的错误。例如，在约束失败时

+
POST /projects HTTP/1.1
+
+
+
HTTP/1.1 400 Bad Request
+Content-Type: application/json; charset=utf-8
+
+
+
{
+    "code": "23502",
+    "details": "Failing row contains (null, foo, null).",
+    "hint": null,
+    "message": "null value in column \"id\" of relation \"projects\" violates not-null constraint"
+}
+
+
+
+

HTTP 状态码

+

PostgREST 将 PostgreSQL 错误代码 转换为 HTTP 状态，如下所示

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

PostgreSQL 错误代码

HTTP 状态

错误描述

08*

503

pg 连接错误

09*

500

触发操作异常

0L*

403

无效授予者

0P*

403

无效角色规范

23503

409

外键冲突

23505

409

唯一性冲突

25006

405

只读 SQL 事务

25*

500

无效的事务状态

28*

403

无效的授权规范

2D*

500

无效的事务终止

38*

500

外部例程异常

39*

500

外部例程调用

3B*

500

保存点异常

40*

500

事务回滚

53400

500

配置限制超出

53*

503

资源不足

54*

500

过于复杂

55*

500

对象不在先决条件状态

57*

500

操作员干预

58*

500

系统错误

F0*

500

配置文件错误

HV*

500

外部数据包装器错误

P0001

400

“raise”的默认代码

P0*

500

PL/pgSQL 错误

XX*

500

内部错误

42883

404

未定义函数

42P01

404

未定义表

42P17

500

无限递归

42501

+
如果已认证，则返回 403，
+
否则返回 401
+
+

权限不足

其他

400

+
+
+
+

来自 PostgREST 的错误

+

来自 PostgREST 本身的错误保持相同的结构，但在 code 字段中使用 PGRST 前缀。例如，当查询在 schema 缓存 中不存在的函数时

+
POST /rpc/nonexistent_function HTTP/1.1
+
+
+
HTTP/1.1 404 Not Found
+Content-Type: application/json; charset=utf-8
+
+
+
{
+  "hint": "...",
+  "details": null
+  "code": "PGRST202",
+  "message": "Could not find the api.nonexistent_function() function in the schema cache"
+}
+
+
+
+

PostgREST 错误代码

+

PostgREST 错误代码的格式为 PGRSTgxx。

+
    +

  • PGRST 是区分错误与 PostgreSQL 错误的前缀。

    • +

  • g 是错误组

    • +

  • xx 是组中的错误标识符。

    • +
+
+

组 0 - 连接

+

与数据库的连接相关。

+
+ + + + + + + + + + + + + + + + + + + + + + + + +

代码

HTTP 状态

描述

PGRST000

+

503

由于 db-uri 不正确或 PostgreSQL 服务未运行，无法连接到数据库。

PGRST001

+

503

由于内部错误，无法连接到数据库。

PGRST002

+

503

在构建 Schema Cache 时无法连接到数据库，因为 PostgreSQL 服务未运行。

PGRST003

+

504

请求在等待连接池可用时超时。请参阅 db-pool-acquisition-timeout。

+
+
+

组 1 - API 请求

+

与 HTTP 请求元素相关。

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

代码

HTTP 状态

描述

PGRST100

+

400

查询字符串参数解析错误。请参阅 水平过滤、运算符 和 排序。

PGRST101

+

405

对于 函数，只允许使用 GET 和 POST 动词。任何其他动词都会抛出此错误。

PGRST102

+

400

发送了无效的请求主体（例如空主体或格式错误的 JSON）。

PGRST103

+

416

为 限制和分页 指定了无效的范围。

PGRST105

+

405

执行了无效的 PUT 请求。

PGRST106

+

406

在 切换模式 时指定的模式不存在于 db-schemas 配置变量中。

PGRST107

+

415

请求中发送的 Content-Type 无效。

PGRST108

+

400

过滤器应用于未在查询字符串的 select 部分中指定的嵌入式资源。请参阅 嵌入式过滤器。

PGRST109

+

400

使用限制来限制删除或更新必须包含唯一列的排序。请参阅 限制更新/删除。

PGRST110

+

400

当使用限制来限制删除或更新时，修改的行数超过限制中指定的最大值。请参阅 限制更新/删除。

PGRST111

+

500

设置了无效的 response.headers。请参阅 响应头。

PGRST112

+

500

状态代码必须是正整数。请参阅 响应状态代码。

PGRST114

+

400

对于使用 PUT 的 UPSERT，当使用 限制和偏移量 时。

PGRST115

+

400

对于使用 PUT 的 UPSERT，当查询字符串中的主键与主体中的主键不同时。

PGRST116

+

406

在请求单个响应时，返回了多个或没有项目。请参阅 单数或复数。

PGRST117

+

405

请求中使用的 HTTP 动词不受支持。

PGRST118

+

400

无法使用相关表对结果进行排序，因为它们之间没有多对一或一对一关系。

PGRST119

+

400

无法在相关表上使用扩展运算符，因为它们之间没有多对一或一对一关系。

PGRST120

+

400

嵌入式资源只能使用 is.null 或 not.is.null 运算符 进行过滤。

PGRST121

+

500

PostgREST 无法解析 RAISE PGRST 错误中的 JSON 对象。请参阅 raise 标头。

PGRST122

+

400

在 Prefer 标头中发现无效的偏好设置，其中 Prefer: handling=strict。请参阅 严格或宽松处理。

+
+
+

第 2 组 - 架构缓存

+

与 架构缓存 相关。大多数情况下，这些错误可以通过 架构缓存重新加载 解决。

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +

代码

HTTP 状态

描述

PGRST200

+

400

由过时的外键关系引起，否则任何嵌入式资源或关系本身可能不存在于数据库中。

PGRST201

+

300

发出了不明确的嵌入请求。请参阅 多个外键关系上的外键连接。

PGRST202

+

404

由过时的函数签名引起，否则该函数可能不存在于数据库中。

PGRST203

+

300

由于请求具有相同参数名称但类型不同的重载函数，或使用 POST 动词请求具有 JSON 或 JSONB 类型未命名参数的重载函数而导致。解决方法是重命名函数或添加/修改参数名称。

PGRST204

+

400

当 columns 查询参数中指定的 列 未找到时导致。

+
+
+

第 3 组 - JWT

+

与使用 JWT 进行身份验证过程相关。您可以参考 教程 1 - 金钥匙 获取有关如何实现身份验证的示例，以及 身份验证页面 获取有关此过程的更多信息。

+
+ + + + + + + + + + + + + + + + + + + + +

代码

HTTP 状态

描述

PGRST300

+

500

配置中缺少 JWT 密钥。

PGRST301

+

401

与 JWT 验证相关的任何错误，这意味着提供的 JWT 在某种程度上无效。

PGRST302

+

401

尝试在 db-anon-role 中未设置匿名角色的情况下，在未进行 身份验证 的情况下进行请求。

+
+
+

第 X 组 - 内部

+

内部错误。如果您遇到任何这些错误，您可能遇到了 PostgREST 错误，请 打开一个问题，我们将很乐意修复它。

+
+ + + + + + + + + + + + +

代码

HTTP 状态

描述

PGRSTX00

+

500

与用于连接到数据库的库相关的内部错误。

+
+
+
+
+

自定义错误

+

您可以使用函数上的 RAISE 语句 自定义错误。

+
+

使用 HTTP 状态代码引发错误

+

可以通过在 函数 中引发 SQL 异常来实现自定义状态代码。例如，以下是一个始终以错误响应的函数

+
CREATE OR REPLACE FUNCTION just_fail() RETURNS void
+  LANGUAGE plpgsql
+  AS $$
+BEGIN
+  RAISE EXCEPTION 'I refuse!'
+    USING DETAIL = 'Pretty simple',
+          HINT = 'There is nothing you can do.';
+END
+$$;
+
+
+

调用函数返回 HTTP 400，并带有主体

+
{
+  "message":"I refuse!",
+  "details":"Pretty simple",
+  "hint":"There is nothing you can do.",
+  "code":"P0001"
+}
+
+
+

自定义 HTTP 状态码的一种方法是根据 PostgREST 错误到状态码映射 抛出特定异常。例如，RAISE insufficient_privilege 将根据情况返回 HTTP 401/403。

+

为了更精确地控制 HTTP 状态码，请抛出 PTxyz 类型的异常。例如，要返回 HTTP 402，请抛出 PT402

+
RAISE sqlstate 'PT402' using
+  message = 'Payment Required',
+  detail = 'Quota exceeded',
+  hint = 'Upgrade your plan';
+
+
+

返回值

+
HTTP/1.1 402 Payment Required
+Content-Type: application/json; charset=utf-8
+
+{
+  "message": "Payment Required",
+  "details": "Quota exceeded",
+  "hint": "Upgrade your plan",
+  "code": "PT402"
+}
+
+
+
+
+

使用 RAISE 添加 HTTP 头

+

为了完全控制头信息和状态，您可以抛出 PGRST SQLSTATE 错误。您可以通过在 PostgreSQL 错误消息字段中添加 code、message、detail 和 hint 作为 JSON 对象来实现。这里，details 和 hint 是可选的。类似地，status 和 headers 必须作为 JSON 对象添加到 SQL 错误详细信息字段中。例如

+
RAISE sqlstate 'PGRST' USING
+    message = '{"code":"123","message":"Payment Required","details":"Quota exceeded","hint":"Upgrade your plan"}',
+    detail = '{"status":402,"headers":{"X-Powered-By":"Nerd Rage"}}';
+
+
+

返回值

+
HTTP/1.1 402 Payment Required
+Content-Type: application/json; charset=utf-8
+X-Powered-By: Nerd Rage
+
+{
+  "message": "Payment Required",
+  "details": "Quota exceeded",
+  "hint": "Upgrade your plan",
+  "code": "123"
+}
+
+
+

对于非标准 HTTP 状态，您可以选择添加 status_text 来描述状态码。对于状态码 419，详细信息字段可能如下所示

+
detail = '{"status":419,"status_text":"Page Expired","headers":{"X-Powered-By":"Nerd Rage"}}';
+
+
+

如果 PostgREST 无法解析 JSON 对象 message 和 detail，它将抛出 PGRST121 错误。请参阅 PostgREST 错误。

+
+
+
+ + +
+