SQLSTATE Mapping
NodeDB maps internal error codes to PostgreSQL SQLSTATE codes for pgwire compatibility.
| NodeDB Error | SQLSTATE | PostgreSQL Meaning |
| Syntax error | 42601 | Syntax error |
| Collection not found | 42P01 | Undefined table |
| Column not found | 42703 | Undefined column |
| Type mismatch | 42846 | Cannot coerce |
| Column outside GROUP BY and aggregates | 42803 | Grouping error |
| Unique violation | 23505 | Unique violation |
| FK violation | 23503 | Foreign key violation |
| Check violation | 23514 | Check violation |
| Not null violation | 23502 | Not null violation |
| Permission denied | 42501 | Insufficient privilege |
| Numeric overflow | 22003 | Numeric value out of range |
| Division by zero | 22012 | Division by zero |
| Rate limit exceeded | 53300 | Too many connections |
| Tenant quota exceeded | 53400 | Configuration limit exceeded |
| Database quota exceeded | 53400 | Configuration limit exceeded |
Server overload (SERVER_OVERLOAD, dispatch capacity) | 57P03 | Cannot connect now |
| Quota overcommit | 53400 | Configuration limit exceeded |
| Database not found | 3D000 | Invalid catalog name (HTTP 404) |
| Mirror read only | 25006 | Read-only SQL transaction |
| Stale read on mirror | 55P03 | Lock not available (redirect to source) |
| Clone depth exceeded | 54011 | Program limit exceeded (class 54) |
| Session not found | 42704 | Undefined object |
| Session idle timeout | 42601 | Syntax error (BAD_REQUEST) |
Session closed: user dropped or KILL SESSION | 42601 | Syntax error (BAD_REQUEST) |
| Internal error | XX000 | Internal error |
Errors reported at Parse
A planning error reaches a driver at Parse (prepare) with its SQLSTATE when the statement has no $N placeholders. Class 42 errors and 0A000 report at Parse. These errors defer to Execute: 42501 (insufficient privilege), data errors of class 22, and retryable errors of class 40.
With placeholders, Parse plans each $N as NULL. It reports only these errors: 42P01 (unknown table), 42703 (unknown column), 42702 (ambiguous column), 42883 (unknown function), and 42803 (column outside GROUP BY). Every other error defers to Execute, which plans with the bound values.
Retryable capacity refusal (57P03)
57P03 is a transient refusal. Its usual cause is a Data Plane dispatch queue at capacity: the server enqueued nothing and ran nothing. A collection that is draining and a migration in progress answer 57P03 too. Retry the same statement with backoff. nodedb_server_overload_responses_total{protocol} counts each 57P03 answer sent. See Error Codes for the full contract.