Skip to content
REST API

错误代码

Identify PostgREST errors and resolve them

PostgREST 错误代码 #

🌐 PostgREST error codes

来自数据 API 的错误代码会作为 JSON 对象返回

🌐 Error codes from the Data API are returned as JSON objects

1
{
2
"code": "42703",
3
"details": null,
4
"hint": "Perhaps you meant to reference the column some_table.fake_col",
5
"message": "column some_table.fake_col does not exist"
6
}

这里是所有错误代码及其说明的完整列表:

🌐 Here is the full list of error codes and their descriptions:

数据库级别错误 #

🌐 Database level errors

要了解错误,请参考 Postgres 错误文档

🌐 To understand the errors reference the Postgres Error Docs.

这是以合适的 Markdown 表格格式编排的文本:

🌐 Here's the text formatted as a proper markdown table:

Postgres 错误代码HTTP 状态错误描述
08*503连接错误
09*500触发动作异常
0L*403无效的授予方
0P*403无效的角色指定
23503409外键冲突
23505409唯一性冲突
25006405只读 SQL 事务
25*500无效交易状态
28*403无效的认证规范
2D*500无效的交易终止
38*500外部例程异常
39*500外部例程调用
3B*500保存点异常
40*500事务回滚
53400500配置限制超出
53*503资源不足
54*500太复杂了
55*500OBJ不在先决条件状态
57*500运算符干预
58*500系统错误
F0*500配置文件错误
HV*500外部数据封装器错误
P0001400“raise”的默认代码
P0*500PL/pgSQL 错误
XX*500内部误差
42883404未定义的函数
42P01404未定义的表
42P17500无限递归
42501如果已认证则返回403,否则返回401权限不足
其他400

API级别错误 #

🌐 API level errors

连接错误 #

🌐 Connection errors

阻止那个数据 API 与 Postgres 交互的错误。

🌐 Errors that prevent that data API from interacting with Postgres.

代码HTTP 状态描述
PGRST000503由于连接字符串错误或 Postgres 服务未运行,无法连接数据库
PGRST001503由于内部错误,无法连接数据库
PGRST002503构建模式缓存时无法连接数据库
PGRST003504请求在等待 PostgREST 内部连接池连接时超时

API请求 #

🌐 API requests

数据结构或请求格式错误

🌐 Errors with data structures or request formatting

代码HTTP 状态描述
PGRST100400查询字符串参数解析错误。
PGRST101405对于数据库函数,只允许 GETPOST 动词。任何其他动词都会抛出此错误。
PGRST102400发送了无效的请求体(例如,空的请求体或格式错误的 JSON)。
PGRST103416为限制指定了无效范围。
PGRST105405发出了无效的 UPDATE/UPSERT 请求
PGRST106406切换模式时指定的模式未向 API 公开。
PGRST107415请求中发送的 Content-Type 无效。
PGRST108400该过滤器应用于查询字符串 select 部分未指定的嵌入资源。
PGRST111500设置了无效的 response.headers
PGRST112500状态码必须是正整数。
PGRST114400当使用 PUTUPSERT 在使用限制和偏移时出现的情况。
PGRST115400当使用 PUTUPSERT 时,如果查询字符串和请求体中的主键不同。
PGRST116406请求单个响应时返回了多于1项或没有项。
PGRST117405请求中使用的 HTTP 方法不被支持。
PGRST118400无法使用相关表对结果进行排序,因为它们之间没有多对一或一对一的关系。
PGRST120400嵌入资源只能使用 is.nullnot.is.null 操作符进行过滤。
PGRST121500API 无法解析 RAISE PGRST 错误中的 JSON 对象。
PGRST122400Prefer 头中发现无效的偏好设置,包含 Prefer: handling=strict
PGRST123400聚合函数已被禁用。
PGRST124400max-affected 偏好被违反。
PGRST125404请求的 URL 中指定了无效路径。
PGRST126404Open API 配置已禁用,但访问了 API 根路径。
PGRST127400details 字段中指定的功能尚未实现。
PGRST128400使用 RPC 调用时违反了 max-affected 偏好。

模式缓存错误 #

🌐 Schema cache errors

这个 API 无法识别查询请求中的关系或对象。

🌐 The API is unable to identify relationships or objects within the query requests.

代码HTTP 状态描述
PGRST200400由过时的外键关系引起,否则可能是嵌入资源或关系本身在数据库中不存在。
PGRST201300发出了模糊的嵌入请求。
PGRST202404由过时的函数签名引起,否则函数可能在数据库中不存在。
PGRST203300由请求使用相同参数名但类型不同的重载函数,或者使用 POST 动词请求带有 JSONJSONB 类型未命名参数的重载函数引起。解决方法是重命名函数或添加/修改参数名称。
PGRST204400当在 columns 查询参数中指定的列未找到时引起。
PGRST205404当 URI 中指定的表未找到时引起。

身份验证错误 #

🌐 Authentication errors

这个请求缺少获取数据的正确凭证

🌐 The request lacks the proper credentials to request data

代码HTTP 状态描述
PGRST300500PostgREST 没有可用的 JWT 密钥来验证请求
PGRST301401提供的 JWT 无法解码或无效
PGRST302401匿名角色被禁用时尝试在没有 Auth: Bearer 头的情况下发起请求
PGRST303401JWT 声明验证或解析失败

内部错误 #

🌐 Internal errors

数据接口错误未指定

🌐 Data API error unspecified

代码HTTP 状态描述
PGRSTX00500与连接数据库所用库相关的内部错误。

查看日志中的错误 #

🌐 Viewing errors in the logs

可以在 日志浏览器 中筛选 API 错误。下面是一些用于筛选和分析 API 错误的有用查询:

🌐 One can filter for API errors in the log explorer. Below are useful queries for filtering and analyzing API errors:

找到所有发生在数据库层的 API 错误 #

🌐 Find all API errors that occurred at the database level

1
select
2
cast(postgres_logs.timestamp as datetime) as timestamp,
3
event_message,
4
parsed.error_severity,
5
parsed.user_name,
6
parsed.query,
7
parsed.detail,
8
parsed.hint,
9
parsed.sql_state_code,
10
parsed.backend_type
11
from
12
postgres_logs
13
cross join unnest(metadata) as metadata
14
cross join unnest(metadata.parsed) as parsed
15
where
16
regexp_contains(parsed.error_severity, 'ERROR|FATAL|PANIC')
17
and parsed.user_name = 'authenticator' -- the authenticator role represents the database API
18
order by timestamp desc
19
limit 100;

从数据 API 找到具体的数据库错误 #

🌐 Find specific database error from the data API

1
select
2
cast(postgres_logs.timestamp as datetime) as timestamp,
3
event_message,
4
parsed.error_severity,
5
parsed.user_name,
6
parsed.query,
7
parsed.detail,
8
parsed.hint,
9
parsed.sql_state_code,
10
parsed.backend_type
11
from
12
postgres_logs
13
cross join unnest(metadata) as metadata
14
cross join unnest(metadata.parsed) as parsed
15
where parsed.sql_state_code like '42501' and parsed.user_name = 'authenticator' -- the authenticator role represents the database API
16
order by timestamp desc
17
limit 100;

查找具体的 API 错误 #

🌐 Find specific API error

1
select
2
cast(timestamp as datetime) as timestamp,
3
status_code,
4
event_message,
5
coalesce(proxy_status, 'not_recorded') as error_codes,
6
path
7
from
8
edge_logs
9
cross join unnest(metadata) as metadata
10
cross join unnest(response) as response
11
cross join unnest(request) as request
12
where
13
status_code >= 300
14
and regexp_contains(path, '^/rest/v1/')
15
and regexp_contains(proxy_status, '(?i)THE_RELEVANT_STATUS_CODE');

按每小时统计每条路径的错误: #

🌐 Count errors per path by hour:

1
select
2
format_timestamp(
3
"%c",
4
timestamp_trunc(cast(edge_logs.timestamp as timestamp), hour),
5
"UTC"
6
) as hour,
7
count(proxy_status) as error_count,
8
path,
9
coalesce(proxy_status, 'not_recorded') as error_codes
10
from
11
edge_logs
12
cross join unnest(metadata) as metadata
13
cross join unnest(response) as response
14
cross join unnest(response.headers) as headers
15
cross join unnest(request) as request
16
where status_code >= 300 and regexp_contains(path, '^/rest/v1/')
17
group by hour, proxy_status, path;

从特定认证用户获取数据API请求 #

🌐 Find data API request from specific authenticated user

1
select
2
cast(timestamp as datetime) as timestamp,
3
event_message,
4
cf_connecting_ip as requesters_ip,
5
url as request_url,
6
request.method as request_method,
7
sb.auth_user as user_id,
8
apikey_payload.role as apikey_role,
9
authorization_payload.role as authorization_token_role,
10
user_agent,
11
city,
12
country,
13
continent,
14
postalCode
15
from
16
edge_logs
17
cross join unnest(metadata) as metadata
18
cross join unnest(request) as request
19
cross join unnest(sb) as sb
20
cross join unnest(jwt) as jwt
21
cross join unnest(jwt.apikey) as jwt_apikey
22
cross join unnest(jwt_apikey.payload) as apikey_payload
23
cross join unnest(authorization) as authorization_key
24
cross join unnest(authorization_key.payload) as authorization_payload
25
cross join unnest(headers) as headers
26
cross join unnest(cf) as cf
27
cross join unnest(response) as response
28
where regexp_contains(path, '^/rest/v1/') and sb.auth_user = 'SOME_USER_ID' -- <---ADD USER_ID from auth.users table
29
order by timestamp desc;