错误代码
Identify PostgREST errors and resolve them
这些文档反映了 PostgREST 官方文档 中的错误代码和信息。
🌐 The docs reflect the error codes and information in PostgREST's official docs.
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 | 无效的角色指定 |
| 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 | OBJ不在先决条件状态 |
| 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 |
API级别错误 #
🌐 API level errors
连接错误 #
🌐 Connection errors
阻止那个数据 API 与 Postgres 交互的错误。
🌐 Errors that prevent that data API from interacting with Postgres.
| 代码 | HTTP 状态 | 描述 |
|---|---|---|
| PGRST000 | 503 | 由于连接字符串错误或 Postgres 服务未运行,无法连接数据库 |
| PGRST001 | 503 | 由于内部错误,无法连接数据库 |
| PGRST002 | 503 | 构建模式缓存时无法连接数据库 |
| PGRST003 | 504 | 请求在等待 PostgREST 内部连接池连接时超时 |
API请求 #
🌐 API requests
数据结构或请求格式错误
🌐 Errors with data structures or request formatting
| 代码 | HTTP 状态 | 描述 |
|---|---|---|
| PGRST100 | 400 | 查询字符串参数解析错误。 |
| PGRST101 | 405 | 对于数据库函数,只允许 GET 和 POST 动词。任何其他动词都会抛出此错误。 |
| PGRST102 | 400 | 发送了无效的请求体(例如,空的请求体或格式错误的 JSON)。 |
| PGRST103 | 416 | 为限制指定了无效范围。 |
| PGRST105 | 405 | 发出了无效的 UPDATE/UPSERT 请求 |
| PGRST106 | 406 | 切换模式时指定的模式未向 API 公开。 |
| PGRST107 | 415 | 请求中发送的 Content-Type 无效。 |
| PGRST108 | 400 | 该过滤器应用于查询字符串 select 部分未指定的嵌入资源。 |
| PGRST111 | 500 | 设置了无效的 response.headers。 |
| PGRST112 | 500 | 状态码必须是正整数。 |
| PGRST114 | 400 | 当使用 PUT 的 UPSERT 在使用限制和偏移时出现的情况。 |
| PGRST115 | 400 | 当使用 PUT 的 UPSERT 时,如果查询字符串和请求体中的主键不同。 |
| PGRST116 | 406 | 请求单个响应时返回了多于1项或没有项。 |
| PGRST117 | 405 | 请求中使用的 HTTP 方法不被支持。 |
| PGRST118 | 400 | 无法使用相关表对结果进行排序,因为它们之间没有多对一或一对一的关系。 |
| PGRST120 | 400 | 嵌入资源只能使用 is.null 或 not.is.null 操作符进行过滤。 |
| PGRST121 | 500 | API 无法解析 RAISE PGRST 错误中的 JSON 对象。 |
| PGRST122 | 400 | 在 Prefer 头中发现无效的偏好设置,包含 Prefer: handling=strict。 |
| PGRST123 | 400 | 聚合函数已被禁用。 |
| PGRST124 | 400 | max-affected 偏好被违反。 |
| PGRST125 | 404 | 请求的 URL 中指定了无效路径。 |
| PGRST126 | 404 | Open API 配置已禁用,但访问了 API 根路径。 |
| PGRST127 | 400 | details 字段中指定的功能尚未实现。 |
| PGRST128 | 400 | 使用 RPC 调用时违反了 max-affected 偏好。 |
模式缓存错误 #
🌐 Schema cache errors
这个 API 无法识别查询请求中的关系或对象。
🌐 The API is unable to identify relationships or objects within the query requests.
| 代码 | HTTP 状态 | 描述 |
|---|---|---|
| PGRST200 | 400 | 由过时的外键关系引起,否则可能是嵌入资源或关系本身在数据库中不存在。 |
| PGRST201 | 300 | 发出了模糊的嵌入请求。 |
| PGRST202 | 404 | 由过时的函数签名引起,否则函数可能在数据库中不存在。 |
| PGRST203 | 300 | 由请求使用相同参数名但类型不同的重载函数,或者使用 POST 动词请求带有 JSON 或 JSONB 类型未命名参数的重载函数引起。解决方法是重命名函数或添加/修改参数名称。 |
| PGRST204 | 400 | 当在 columns 查询参数中指定的列未找到时引起。 |
| PGRST205 | 404 | 当 URI 中指定的表未找到时引起。 |
身份验证错误 #
🌐 Authentication errors
这个请求缺少获取数据的正确凭证
🌐 The request lacks the proper credentials to request data
| 代码 | HTTP 状态 | 描述 |
|---|---|---|
| PGRST300 | 500 | PostgREST 没有可用的 JWT 密钥来验证请求 |
| PGRST301 | 401 | 提供的 JWT 无法解码或无效 |
| PGRST302 | 401 | 匿名角色被禁用时尝试在没有 Auth: Bearer 头的情况下发起请求 |
| PGRST303 | 401 | JWT 声明验证或解析失败 |
内部错误 #
🌐 Internal errors
数据接口错误未指定
🌐 Data API error unspecified
| 代码 | HTTP 状态 | 描述 |
|---|---|---|
| PGRSTX00 | 500 | 与连接数据库所用库相关的内部错误。 |
查看日志中的错误 #
🌐 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
1select2 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_type11from12 postgres_logs13 cross join unnest(metadata) as metadata14 cross join unnest(metadata.parsed) as parsed15where16 regexp_contains(parsed.error_severity, 'ERROR|FATAL|PANIC')17 and parsed.user_name = 'authenticator' -- the authenticator role represents the database API18order by timestamp desc19limit 100;从数据 API 找到具体的数据库错误 #
🌐 Find specific database error from the data API
1select2 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_type11from12 postgres_logs13 cross join unnest(metadata) as metadata14 cross join unnest(metadata.parsed) as parsed15where parsed.sql_state_code like '42501' and parsed.user_name = 'authenticator' -- the authenticator role represents the database API16order by timestamp desc17limit 100;PostgREST 错误代码只有在运行 V14+ 的项目的日志中才会被记录。你可以在 基础设施设置 中查看你的 PostgREST 版本并升级你的项目。
🌐 PostgREST error codes are only captured in the logs for projects running V14+. You can check your PostgREST version and upgrade your project in the Infrastructure Settings
查找具体的 API 错误 #
🌐 Find specific API error
1select2 cast(timestamp as datetime) as timestamp,3 status_code,4 event_message,5 coalesce(proxy_status, 'not_recorded') as error_codes,6 path7from8 edge_logs9 cross join unnest(metadata) as metadata10 cross join unnest(response) as response11 cross join unnest(request) as request12where13 status_code >= 30014 and regexp_contains(path, '^/rest/v1/')15 and regexp_contains(proxy_status, '(?i)THE_RELEVANT_STATUS_CODE');按每小时统计每条路径的错误: #
🌐 Count errors per path by hour:
1select2 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_codes10from11 edge_logs12 cross join unnest(metadata) as metadata13 cross join unnest(response) as response14 cross join unnest(response.headers) as headers15 cross join unnest(request) as request16where status_code >= 300 and regexp_contains(path, '^/rest/v1/')17group by hour, proxy_status, path;从特定认证用户获取数据API请求 #
🌐 Find data API request from specific authenticated user
1select2 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 postalCode15from16 edge_logs17 cross join unnest(metadata) as metadata18 cross join unnest(request) as request19 cross join unnest(sb) as sb20 cross join unnest(jwt) as jwt21 cross join unnest(jwt.apikey) as jwt_apikey22 cross join unnest(jwt_apikey.payload) as apikey_payload23 cross join unnest(authorization) as authorization_key24 cross join unnest(authorization_key.payload) as authorization_payload25 cross join unnest(headers) as headers26 cross join unnest(cf) as cf27 cross join unnest(response) as response28where regexp_contains(path, '^/rest/v1/') and sb.auth_user = 'SOME_USER_ID' -- <---ADD USER_ID from auth.users table29order by timestamp desc;