错误

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 error codes 转换为HTTP状态，如下所示：

PostgreSQL错误码(S)	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	外部例程调用
30亿*	500	保存点异常
40*	500	事务回滚
53400	500	超出配置限制
53*	503	资源不足
54*	500	太复杂了
55*	500	OBJ未处于先决条件状态
57*	500	操作员干预
58*	500	系统错误
F0*	500	配置文件错误
HV*	500	外来数据包装错误
P0001	400	“RAISE”的默认代码
P0*	500	Pl/pgSQL错误
XX*	500	内部错误
42883	404	未定义的函数
42P01	404	未定义的表
42 P17	500	无限递归
42501	如果认证403， 否则401	特权不足
其他	400

来自PostgREST的错误

来自PostgREST本身的错误保持相同的结构，但在 PGRST 中的前缀 code 菲尔德。例如，当查询不存在于 schema cache ：

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-获取-超时 。

组1-API请求

与HTTP请求元素相关。

代码	HTTP状态	描述
PGRST100	400	查询字符串参数中的分析错误。看见 水平滤波 ， 操作员 和 有序化 。
PGRST101	405	为 functions ，仅限 GET 和 POST 允许使用动词。任何其他动词都会抛出此错误。
PGRST102	400	发送了无效的请求正文(例如，空正文或格式错误的JSON)。
PGRST103	416	为以下项指定的范围无效 限制和分页 。
PGRST105	405	一个残废 PUT 请求已完成
PGRST106	406	时指定的架构 switching schemas 不存在于 DB-架构 配置变量。
PGRST107	415	这个 Content-Type 请求中发送的消息无效。
PGRST108	400	筛选器应用于未在 select 查询字符串的一部分。看见 嵌入式滤镜 。
PGRST111	500	一个残废 response.headers 已经设置好了。看见 响应标头 。
PGRST112	500	状态代码必须是正整数。看见 响应状态代码 。
PGRST114	400	对于一个 UPSERT using PUT ，何时 limits and offsets 都被使用过。
PGRST115	400	对于一个 UPSERT using PUT 当查询字符串中的主键与正文中的主键不同时。
PGRST116	406	请求单一响应时，返回的项目超过1个或未返回任何项目。看见 单数或复数 。
PGRST117	405	不支持请求中使用的HTTP谓词。
PGRST118	400	无法使用关联表对结果进行排序，因为它们之间不存在多对一或一对一关系。
PGRST120	400	嵌入的资源只能使用 is.null 或 not.is.null operators 。
PGRST121	500	PostgREST无法分析RAISE中的JSON对象 PGRST 错误。看见 raise headers 。
PGRST122	400	在中找到无效的首选项 Prefer 标题为 Prefer: handling=strict 。看见 从严从宽处理 。
PGRST 123	400	聚合功能已禁用。看到 数据库-已启用聚合 .
PGRST 124	400	max-affected 偏好被侵犯了。看到 受影响的最大值 .
PGRST 125	404	请求URL中指定的路径无效。
PGRST 126	404	打开API配置已禁用，但API根路径已访问。看到 Openapi-模式 .
PGRST 127	400	中指定的功能 details 字段未实现。

组2-架构缓存

与一个 架构缓存 。大多数情况下，这些错误是通过以下方式解决的 架构缓存重新加载 。

代码	HTTP状态	描述
PGRST200	400	由过时的外键关系引起，否则数据库中可能不存在任何嵌入资源或关系本身。
PGRST201	300	提出了不明确的嵌入请求。看见 多个外键关系上的外键联接 。
PGRST202	404	由过时的函数签名引起，否则该函数可能不存在于数据库中。
PGRST203	300	由于请求具有相同参数名称但类型不同的重载函数，或者使用 POST 用来请求重载函数的谓词 JSON 或 JSONB 键入未命名参数。解决方案是重命名函数或添加/修改参数的名称。
PGRST204	400	导致的原因是 column specified 在 columns 未找到查询参数。
PGRST205	404	时引起 table specified 在URI中找不到。

第三组-JWT

与使用JWT的身份验证过程相关。您可以按照 教程1-金钥匙 有关如何实现身份验证和 Authentication page 有关此过程的更多信息，请参阅。

代码	HTTP状态	描述
PGRST300	500	A JWT secret 配置中缺少。
PGRST301	401	提供的JWT无法解码或无效。
PGRST302	401	尝试执行请求时不带 authentication 通过不在中设置匿名角色来禁用它 DB-anon-角色 。
PGRST 303	401	JWT claims validation 或解析失败。

X组--内部

内部错误。如果您遇到其中的任何一个，您可能无意中发现了一个PostgREST错误，请 open an issue 我们很乐意把它修好。

代码	HTTP状态	描述
PGRSTX00	500	与用于连接到数据库的库相关的内部错误。

自定义错误

您可以通过使用 RAISE statement 关于函数。

引发带有HTTP状态代码的错误

自定义状态代码可以通过在内部引发SQL异常来完成 functions 。例如，下面是一个时髦的函数，它总是以错误响应：

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
$$;

调用该函数将返回带有正文的HTTP400

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

定制HTTP状态代码的一种方法是根据PostgREST引发特定异常 error to status code mapping 。例如, RAISE insufficient_privilege 将根据需要使用HTTP 401/403进行响应。

为了更好地控制HTTP状态代码，请引发 PTxyz 打字。例如，使用HTTP402进行响应，引发 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错误。您可以通过添加 code ， message ， detail 和 hint 在作为JSON对象的PostgreSQL错误消息字段中。在这里， 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 错误。看见 Errors from PostgREST 。

代理状态标题

对于错误情况，标准 Proxy-Status 返回标头并带有错误代码。错误代码来自 PostgREST , PostgreSQL 或 Custom 错误.这在做什么时很有用 HEAD HTTP状态描述性不够的请求。

例如，在一个高计数的表上执行一个请求（比如30_000_000），我们得到：

HEAD /table HTTP/1.1
Prefer: count=exact

HTTP/1.1 500 Internal Server Error
Proxy-Status: PostgREST; error=57014

The PostgreSQL error code 57014 (ref) reveals that the error is due to a short statement_timeout value.