Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs: added postgrest error codes (#42369)

TheOtherBrian164b2c52d5104
diff --git a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
index e08c2d9aad2..a57f010ade7 100644
--- a/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
+++ b/apps/docs/components/Navigation/NavigationMenu/NavigationMenu.constants.ts
@@ -1499,6 +1499,7 @@ export const api: NavMenuConstant = {
{ name: 'Creating API routes', url: '/guides/api/creating-routes' },
{ name: 'How API Keys work', url: '/guides/api/api-keys' },
{ name: 'Securing your API', url: '/guides/api/securing-your-api' },
+ { name: 'Error Codes', url: '/guides/api/rest/postgrest-error-codes' },
],
},
{
diff --git a/apps/docs/content/guides/api/rest/postgrest-error-codes.mdx b/apps/docs/content/guides/api/rest/postgrest-error-codes.mdx
new file mode 100644
index 00000000000..635d2837203
--- /dev/null
+++ b/apps/docs/content/guides/api/rest/postgrest-error-codes.mdx
@@ -0,0 +1,276 @@
+---
+id: 'postgrest-error-codes'
+title: 'Error Codes'
+description: 'PostgREST Error Codes'
+subtitle: 'Identify PostgREST errors and resolve them'
+sidebar_label: 'Debugging'
+---
+
+<Admonition type="note">
+
+The docs reflect the error codes and information in [PostgREST's official
+docs](https://docs.postgrest.org/en/stable/).
+
+</Admonition>
+
+## PostgREST error codes
+
+Error codes from the Data API are returned as JSON objects
+
+```json
+{
+ "code": "42703",
+ "details": null,
+ "hint": "Perhaps you meant to reference the column some_table.fake_col",
+ "message": "column some_table.fake_col does not exist"
+}
+```
+
+Here is the full list of error codes and their descriptions:
+
+## Database level errors
+
+To understand the errors reference the [Postgres Error Docs](https://www.postgresql.org/docs/current/errcodes-appendix.html).
+
+Here's the text formatted as a proper markdown table:
+
+| Postgres error code(s) | HTTP status | Error description |
+| ---------------------- | ------------------------------ | ------------------------------- |
+| 08\* | 503 | connection error |
+| 09\* | 500 | triggered action exception |
+| 0L\* | 403 | invalid grantor |
+| 0P\* | 403 | invalid role specification |
+| 23503 | 409 | foreign key violation |
+| 23505 | 409 | uniqueness violation |
+| 25006 | 405 | read only SQL transaction |
+| 25\* | 500 | invalid transaction state |
+| 28\* | 403 | invalid auth specification |
+| 2D\* | 500 | invalid transaction termination |
+| 38\* | 500 | external routine exception |
+| 39\* | 500 | external routine invocation |
+| 3B\* | 500 | savepoint exception |
+| 40\* | 500 | transaction rollback |
+| 53400 | 500 | config limit exceeded |
+| 53\* | 503 | insufficient resources |
+| 54\* | 500 | too complex |
+| 55\* | 500 | obj not in prerequisite state |
+| 57\* | 500 | operator intervention |
+| 58\* | 500 | system error |
+| F0\* | 500 | config file error |
+| HV\* | 500 | foreign data wrapper error |
+| P0001 | 400 | default code for "raise" |
+| P0\* | 500 | PL/pgSQL error |
+| XX\* | 500 | internal error |
+| 42883 | 404 | undefined function |
+| 42P01 | 404 | undefined table |
+| 42P17 | 500 | infinite recursion |
+| 42501 | if authenticated 403, else 401 | insufficient privileges |
+| other | 400 | |
+
+## API level errors
+
+### Connection errors
+
+Errors that prevent that data API from interacting with Postgres.
+
+| Code | HTTP status | Description |
+| -------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
+| PGRST000 | 503 | Could not connect with the database due to an incorrect connection string or due to the Postgres service not running. |
+| PGRST001 | 503 | Could not connect with the database due to an internal error. |
+| PGRST002 | 503 | Could not connect with the database when building the schema cache |
+| PGRST003 | 504 | The request timed out waiting for a connection from PostgREST's internal pool |
+
+### API requests
+
+Errors with data structures or request formatting
+
+| Code | HTTP status | Description |
+| -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------- |
+| PGRST100 | 400 | Parsing error in the query string parameter. |
+| PGRST101 | 405 | For database functions, only `GET` and `POST` verbs are allowed. Any other verb will throw this error. |
+| PGRST102 | 400 | An invalid request body was sent(e.g. an empty body or malformed JSON). |
+| PGRST103 | 416 | An invalid range was specified for limits. |
+| PGRST105 | 405 | An invalid `UPDATE`/`UPSERT` request was done |
+| PGRST106 | 406 | The schema specified when switching schemas is not exposed to the API. |
+| PGRST107 | 415 | The `Content-Type` sent in the request is invalid. |
+| PGRST108 | 400 | The filter is applied to an embedded resource that is not specified in the `select` part of the query string. |
+| PGRST111 | 500 | An invalid `response.headers` was set. |
+| PGRST112 | 500 | The status code must be a positive integer. |
+| PGRST114 | 400 | For an `UPSERT` using `PUT` when limits and offsets are used. |
+| PGRST115 | 400 | For an `UPSERT` using `PUT` when the primary key in the query string and the body are different. |
+| PGRST116 | 406 | More than 1 or no items where returned when requesting a singular response. |
+| PGRST117 | 405 | The HTTP verb used in the request in not supported. |
+| PGRST118 | 400 | Could not order the result using the related table because there is no many-to-one or one-to-one relationship between them. |
+| PGRST120 | 400 | An embedded resource can only be filtered using the `is.null` or `not.is.null` operators. |
+| PGRST121 | 500 | API can't parse the JSON objects in RAISE `PGRST` error. |
+| PGRST122 | 400 | Invalid preferences found in `Prefer` header with `Prefer: handling=strict`. |
+| PGRST123 | 400 | Aggregate functions are disabled. |
+| PGRST124 | 400 | `max-affected` preference is violated. |
+| PGRST125 | 404 | Invalid path is specified in request URL. |
+| PGRST126 | 404 | Open API config is disabled but API root path is accessed. |
+| PGRST127 | 400 | The feature specified in the `details` field is not implemented. |
+| PGRST128 | 400 | `max-affected` preference is violated with `RPC` call. |
+
+### Schema cache errors
+
+The API is unable to identify relationships or objects within the query requests.
+
+| Code | HTTP status | Description |
+| -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| PGRST200 | 400 | Caused by stale foreign key relationships, otherwise any of the embedding resources or the relationship itself may not exist in the database. |
+| PGRST201 | 300 | An ambiguous embedding request was made. |
+| PGRST202 | 404 | Caused by a stale function signature, otherwise the function may not exist in the database. |
+| PGRST203 | 300 | Caused by requesting overloaded functions with the same argument names but different types, or by using a `POST` verb to request overloaded functions with a `JSON` or `JSONB` type unnamed parameter. The solution is to rename the function or add/modify the names of the arguments. |
+| PGRST204 | 400 | Caused when the column specified in the columns query parameter is not found. |
+| PGRST205 | 404 | Caused when the table specified in the URI is not found. |
+
+### Authentication errors
+
+The request lacks the proper credentials to request data
+
+| Code | HTTP status | Description |
+| -------- | ----------- | ------------------------------------------------------------------------------------------------ |
+| PGRST300 | 500 | PostgREST does not have an active JWT secret to validate requests |
+| PGRST301 | 401 | Provided JWT couldn't be decoded or it is invalid. |
+| PGRST302 | 401 | Attempted to do a request without the header `Auth: Bearer` when the anonymous role is disabled. |
+| PGRST303 | 401 | JWT claims validation or parsing failed. |
+
+### Internal errors
+
+Data API error unspecified
+
+| Code | HTTP status | Description |
+| -------- | ----------- | --------------------------------------------------------------------------- |
+| PGRSTX00 | 500 | Internal errors related to the library used for connecting to the database. |
+
+## Viewing errors in the logs
+
+One can filter for API errors in the [log explorer](/dashboard/project/_/logs/explorer). Below are useful queries for filtering and analyzing API errors:
+
+#### Find all API errors that occurred at the database level
+
+```sql
+select
+ cast(postgres_logs.timestamp as datetime) as timestamp,
+ event_message,
+ parsed.error_severity,
+ parsed.user_name,
+ parsed.query,
+ parsed.detail,
+ parsed.hint,
+ parsed.sql_state_code,
+ parsed.backend_type
+from
+ postgres_logs
+ cross join unnest(metadata) as metadata
+ cross join unnest(metadata.parsed) as parsed
+where
+ regexp_contains(parsed.error_severity, 'ERROR|FATAL|PANIC')
+ and parsed.user_name = 'authenticator' -- the authenticator role represents the database API
+order by timestamp desc
+limit 100;
+```
+
+#### Find specific database error from the data API
+
+```sql
+select
+ cast(postgres_logs.timestamp as datetime) as timestamp,
+ event_message,
+ parsed.error_severity,
+ parsed.user_name,
+ parsed.query,
+ parsed.detail,
+ parsed.hint,
+ parsed.sql_state_code,
+ parsed.backend_type
+from
+ postgres_logs
+ cross join unnest(metadata) as metadata
+ cross join unnest(metadata.parsed) as parsed
+where parsed.sql_state_code like '42501' and parsed.user_name = 'authenticator' -- the authenticator role represents the database API
+order by timestamp desc
+limit 100;
+```
+
+<Admonition type="note">
+
+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](/dashboard/project/_/settings/infrastructure)
+
+</Admonition>
+
+#### Find specific API error
+
+```sql
+select
+ cast(timestamp as datetime) as timestamp,
+ status_code,
+ event_message,
+ coalesce(proxy_status, 'not_recorded') as error_codes,
+ path
+from
+ edge_logs
+ cross join unnest(metadata) as metadata
+ cross join unnest(response) as response
+ cross join unnest(request) as request
+where
+ status_code >= 300
+ and regexp_contains(path, '^/rest/v1/')
+ and regexp_contains(proxy_status, '(?i)THE_RELEVANT_STATUS_CODE');
+```
+
+#### Count errors per path by hour:
+
+```sql
+select
+ format_timestamp(
+ "%c",
+ timestamp_trunc(cast(edge_logs.timestamp as timestamp), hour),
+ "UTC"
+ ) as hour,
+ count(proxy_status) as error_count,
+ path,
+ coalesce(proxy_status, 'not_recorded') as error_codes
+from
+ edge_logs
+ cross join unnest(metadata) as metadata
+ cross join unnest(response) as response
+ cross join unnest(response.headers) as headers
+ cross join unnest(request) as request
+where status_code >= 300 and regexp_contains(path, '^/rest/v1/')
+group by hour, proxy_status, path;
+```
+
+#### Find data API request from specific authenticated user
+
+```sql
+select
+ cast(timestamp as datetime) as timestamp,
+ event_message,
+ cf_connecting_ip as requesters_ip,
+ url as request_url,
+ request.method as request_method,
+ sb.auth_user as user_id,
+ apikey_payload.role as apikey_role,
+ authorization_payload.role as authorization_token_role,
+ user_agent,
+ city,
+ country,
+ continent,
+ postalCode
+from
+ edge_logs
+ cross join unnest(metadata) as metadata
+ cross join unnest(request) as request
+ cross join unnest(sb) as sb
+ cross join unnest(jwt) as jwt
+ cross join unnest(jwt.apikey) as jwt_apikey
+ cross join unnest(jwt_apikey.payload) as apikey_payload
+ cross join unnest(authorization) as authorization_key
+ cross join unnest(authorization_key.payload) as authorization_payload
+ cross join unnest(headers) as headers
+ cross join unnest(cf) as cf
+ cross join unnest(response) as response
+where regexp_contains(path, '^/rest/v1/') and sb.auth_user = 'SOME_USER_ID' -- <---ADD USER_ID from auth.users table
+order by timestamp desc;
+```
diff --git a/supa-mdx-lint/Rule003Spelling.toml b/supa-mdx-lint/Rule003Spelling.toml
index 62b4e6aa8f1..821d05fe0a3 100644
--- a/supa-mdx-lint/Rule003Spelling.toml
+++ b/supa-mdx-lint/Rule003Spelling.toml
@@ -70,6 +70,7 @@ allow_list = [
"[Gg]eolocation",
"[Gg]lobs?",
"[Gg]lobstar",
+ "[Gg]rantor",
"[Gg]rayscale",
"[Gg]zip(s|ped|ping)?",
"[Hh]r",
@@ -300,7 +301,9 @@ allow_list = [
"Refine",
"Roboflow",
"SaaS",
+ "[Ss]avepoint",
"SDKs",
+ "SQL",
"SQLAlchemy",
"SQLModel",
"SQLite",