--- title: "Error Codes" description: "SQLSTATE error codes returned by PgBeam, what causes them, and how to resolve each one." canonical: "https://pgbeam.com/docs/error-codes" last-updated: "2026-09-14T19:37:21.000Z" --- # Error Codes > SQLSTATE error codes returned by PgBeam, what causes them, and how to resolve each one. URL: https://pgbeam.com/docs/error-codes PgBeam returns standard PostgreSQL SQLSTATE error codes. This reference covers every PgBeam-specific error, what triggers it, and how to fix it. ## Quick reference SQLSTATE Situation Message `08004` Unknown project `project not found for hostname ...` `08004` Organization suspended `organization suspended — update payment at dash.pgbeam.com` `08004` IP not allowed `connection rejected: IP not in allowlist` `08004` Auth rate limited `too many authentication attempts` `08006` Upstream auth failure Forwarded from upstream `08006` Circuit breaker open `upstream unavailable (circuit breaker open)` `53300` Connection limit exceeded `too many connections for project` `53400` Query rate limit exceeded `query rate limit exceeded` ## `08004`: Connection rejected SQLSTATE `08004` means PgBeam rejected the connection before it reached the upstream database. The three causes are distinct: ## Project not found **Cause:** The hostname in the connection string does not match any project. This usually means a typo in the hostname or a deleted project. **Fix:** Verify the hostname in your `DATABASE_URL` matches the project hostname shown in the dashboard Check that the project has not been deleted If using a custom domain, confirm the domain is verified. See Custom Domains ## Organization suspended **Cause:** The organization's billing is inactive. This happens when a payment fails, the trial expires without a payment method on file, or an owner manually cancels the subscription. **Fix:** Log in to dash.pgbeam.com and go to **Settings > Billing** Update the payment method or reactivate the subscription Connections resume immediately after billing is restored ## IP not allowed **Cause:** The project has an IP allowlist configured and the client's source IP does not match any of the allowed CIDR ranges. The connection is rejected before authentication. **Fix:** Check the project's IP allowlist in **Settings > Security** in the dashboard Add the client's IP address or CIDR range to the allowlist If connecting from a cloud environment, make sure the NAT gateway or egress IP is included. Container and serverless platforms often use shared egress IPs that differ from the instance's private IP To disable the allowlist entirely, set it to an empty array ## Auth rate limited **Cause:** Too many failed authentication attempts from the same IP address in a short period. PgBeam rate-limits auth attempts per IP to protect the upstream database from brute-force attacks. **Fix:** Verify your credentials are correct by connecting directly to the origin database Wait for the rate limit window to expire (typically a few minutes) If the issue persists, check for misconfigured clients that are retrying with wrong credentials in a loop ## `08006`: Connection failure SQLSTATE `08006` means PgBeam accepted the connection but could not complete the upstream handshake. ## Upstream auth failure **Cause:** The credentials were forwarded to the origin database and it rejected them. PgBeam passes this error through as-is. **Fix:** Connect directly to the origin database with the same username and password to confirm they work Verify the database name in the PgBeam project configuration matches the actual database Check that the user has `CONNECT` permission on the database If the origin uses `pg_hba.conf` rules, confirm the PgBeam IP range is allowed ## Circuit breaker open **Cause:** The origin database failed 3 consecutive connection attempts. PgBeam opens a circuit breaker to stop sending traffic to an unhealthy upstream. The breaker probes for recovery every 5 seconds, backing off exponentially up to 60 seconds. **Fix:** Check the health of your origin database. Can you connect to it directly? Verify network connectivity between PgBeam and the origin (firewall rules, security groups, IP allowlists) Check if the origin has hit its own connection limit (`max_connections` in PostgreSQL) Wait for the circuit breaker to probe and recover automatically, or restart the origin database if it is down See Resilience for details on circuit breaker behavior. ## `53300`: Too many connections **Cause:** The project has reached its concurrent connection limit. Each plan tier has a maximum number of simultaneous connections: Plan Connection limit Starter 20 Pro 100 Scale 500 **Fix:** **Reduce client-side pool size.** If you are running multiple application instances, each with a pool of 20 connections, they add up quickly. With PgBeam handling upstream pooling, a client-side pool of 3-5 per instance is usually sufficient. **Switch to transaction pool mode.** Session mode (the default) holds an upstream connection for the entire client session. Transaction mode releases it after each transaction, dramatically improving connection reuse. See Connection Pooling. **Close idle connections.** Check for long-lived idle connections from monitoring tools, migration scripts, or dev environments that hold connections open unnecessarily. **Upgrade your plan** if the workload has genuinely outgrown the current tier. ## `53400`: Query rate limit exceeded **Cause:** The project exceeded its queries-per-second (QPS) limit: Plan QPS limit Starter 10 Pro 50 Scale 250 **Fix:** **Enable caching** for frequently repeated reads. Cached queries do not count against the QPS limit at the upstream. See Caching. **Reduce query frequency.** Batch reads where possible, or add application-level deduplication for concurrent identical queries. **Upgrade your plan** for a higher QPS allowance. ## Handling errors in application code Most PostgreSQL drivers expose the SQLSTATE code programmatically. Use it to distinguish PgBeam-specific errors from upstream database errors: ## Further reading Troubleshooting: Step-by-step debug workflows for common failures Resilience: Circuit breaker states, scale-to-zero, and recovery behavior Plans & Limits: Connection, QPS, and query quotas per plan tier