Error Source

For the most part, error messages will come directly from the database with the same structure that PostgreSQL uses. PostgREST will convert the MESSAGE, DETAIL, HINT and ERRCODE from the PostgreSQL error to JSON format and add an HTTP status code to the response (see HTTP Status Codes). For instance, this is the error you will get when querying a nonexistent table:

GET /nonexistent_table?id=eq.1 HTTP/1.1

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "hint": null,
  "details": null,
  "code": "42P01",
  "message": "relation \"api.nonexistent_table\" does not exist"
}

However, some errors do come from PostgREST itself (such as those related to the Schema Cache). These have the same structure as the PostgreSQL errors but are differentiated by the PGRST prefix in the code field (see PostgREST Error Codes). For instance, when querying a function that does not exist, the error will be:

POST /rpc/nonexistent_function HTTP/1.1

HTTP/1.1 404 Not Found
Content-Type: application/json; charset=utf-8

{
  "hint": "If a new function was created in the database with this name and parameters, try reloading the schema cache.",
  "details": null
  "code": "PGRST202",
  "message": "Could not find the api.nonexistent_function() function in the schema cache"
}

HTTP Status Codes

PostgREST translates PostgreSQL error codes into HTTP status as follows:

PostgreSQL error code(s)	HTTP status	Error description
08*	503	pg connection err
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
53*	503	insufficient resources
54*	413	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
42501	if authenticated 403, else 401	insufficient privileges
other	400

PostgREST Error Codes

PostgREST error codes have the form PGRSTgxx, where PGRST is the prefix that differentiates the error from a PostgreSQL error, g is the group where the error belongs and xx is the number that identifies the error in the group.

Group 0 - Connection

Related to the connection with the database.

Code	HTTP status	Description
PGRST000	503	Could not connect with the database due to an incorrect db-uri or due to the PostgreSQL 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 due to the PostgreSQL service not running.
PGRST003	504	The request timed out waiting for a pool connection to be available. See db-pool-acquisition-timeout.

Group 1 - Api Request

Related to the HTTP request elements.

Code	HTTP status	Description
PGRST100	400	Parsing error in the query string parameter. See Horizontal Filtering (Rows), Operators and Ordering.
PGRST101	405	For 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 and Pagination.
PGRST105	405	An invalid PUT request was done
PGRST106	406	The schema specified when switching schemas is not present in the db-schemas configuration variable.
PGRST107	415	The `Content-Type` sent in the request is invalid.
PGRST108	400	The filter is applied to a embedded resource that is not specified in the `select` part of the query string. See Embedded Filters.
PGRST109	400	Restricting a Deletion or an Update using limits must include the ordering of a unique column. See Limited Updates/Deletions.
PGRST110	400	When restricting a Deletion or an Update using limits modifies more rows than the maximum specified in the limit. See Limited Updates/Deletions.
PGRST111	500	An invalid `response.headers` was set. See Setting Response Headers.
PGRST112	500	The status code must be a positive integer. See Setting Response Status Code.
PGRST113	406	More than one column was returned for a scalar result. See Response Formats For Scalar Responses.
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. See Singular or Plural.
PGRST117	405	The HTTP verb used in the request in not supported.

Group 2 - Schema Cache

Related to a stale schema cache. Most of the time, these errors are solved by reloading the schema cache.

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. See Embedding Disambiguation.
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.

Group 3 - JWT

Related to the authentication process using JWT. You can follow the Tutorial 1 - The Golden Key for an example on how to implement authentication and the Authentication page for more information on this process.

Code	HTTP status	Description
PGRST300	500	A JWT secret is missing from the configuration.
PGRST301	401	Any error related to the verification of the JWT, which means that the JWT provided is invalid in some way.
PGRST302	401	Attempted to do a request without authentication when the anonymous role is disabled by not setting it in db-anon-role.

Group X - Internal

Internal errors. If you encounter any of these, you may have stumbled on a PostgREST bug, please open an issue and we’ll be glad to fix it.

Code	HTTP status	Description
PGRSTX00	500	Internal errors related to the library used for connecting to the database.