Error Codes

A failed request comes back with a code telling you what went wrong.

Response shape

code and message are always there. hint comes along when there is something worth adding.


{
  "code": "PGRST205",
  "message": "Could not find the table 'orders'.",
  "hint": "Turn its API access on in Gridie, or check the name."
}

The codes

Status	Code	Meaning
401	`PGRST301`	The key is missing, malformed, revoked or expired
403	`PGRST302`	A read-only key tried to write, or the key has no table access
404	`PGRST205`	The table could not be found
400	`PGRST100`	A filter or order could not be parsed
400	`PGRST101`	A request this endpoint does not handle
400	`PGRST102`	The body is not shaped as expected
400	`PGRST204`	The request names a column that does not exist
400	`PGRST200`	The query was built but failed to run
406	`PGRST116`	A single object was requested but the result was not one row
500	`PGRST000`	Looking up the tables for this key failed

Things to check

If you get a 404

PGRST205 answers the same way whether the name is wrong, the table’s API access is off, or the person who issued the key cannot read it. Telling them apart would let a key holder probe the workspace for table names.

Call GET /api/v1/tables to see what this key can actually reach.

If a column name is rejected

PGRST204 means check your column names. The name shown in the Gridie interface can differ from the real column name. In the GET /api/v1/tables response, columns[].name is what requests use and columns[].label is what the interface shows.

If a value is rejected

PGRST200 means the syntax was fine but the database refused. A value whose type does not match the column, an empty NOT NULL column, or a constraint violation. We never pass the raw database error outward.

If a key stops working

Revoking and expiry take effect immediately, so the next request returns 401. Check the key’s state in settings and issue a new one if you need to. A key is shown once at the moment it is issued, so a lost key gets revoked and replaced.