错误#

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	事务回滚
53*	503	资源不足
54*	413	太复杂了
55*	500	OBJ未处于先决条件状态
57*	500	操作员干预
58*	500	系统错误
F0*	500	配置文件错误
HV*	500	外来数据包装错误
P0001	400	“RAISE”的默认代码
P0*	500	Pl/pgSQL错误
XX*	500	内部错误
42883	404	未定义的函数
42P01	404	未定义的表
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` 查询字符串的一部分。看见嵌入式滤镜。
PGRST109	400	使用LIMITS限制删除或更新必须包括唯一列的排序。看见有限的更新/删除。
PGRST110	400	当限制删除或更新时，使用限制修改的行数超过限制中指定的最大行数。看见有限的更新/删除。
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	无法使用关联表对结果进行排序，因为它们之间不存在多对一或一对一关系。
PGRST119	400	无法在相关表上使用扩展运算符，因为它们之间不存在多对一或一对一关系。
PGRST120	400	嵌入的资源只能使用 `is.null` 或 `not.is.null` operators 。
PGRST121	400	PostgREST无法分析RAISE中的JSON对象 `PGRST` 错误。看见 raise headers 。
PGRST122	400	在中找到无效的首选项 `Prefer` 标题为 `Prefer: handling=strict` 。看见从严从宽处理。

组2-架构缓存#

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

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

第三组-JWT#

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

代码	HTTP状态	描述
PGRST300	500	A JWT secret 配置中缺少。
PGRST301	401	任何与JWT验证相关的错误，这意味着提供的JWT在某种程度上是无效的。
PGRST302	401	尝试执行请求时不带 authentication 通过不在中设置匿名角色来禁用它 DB-anon-角色。

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 。