Server: PostgresPoolError

Thrown when the Postgres pool cannot hand a query a connection: every pooled connection stayed busy for the whole checkout wait, or new connection attempts are paused after one failed.

Always has status: 503. Both conditions are transient, so the request can be retried. details.retryAfterMs gives the time left when a pause is running.

ctx.postgres and ctx.postgresAdmin throw this from the query call. The middleware do not turn it into a response; the handler or the host's error handler decides how the request answers.

Parameters

• source

  (Required)

  Always `"@supabase/server"`.

• code

  (Required)

  Machine-readable error code.

• hint

  (Optional)

  Actionable next step, when one applies.

• docs

  (Required)

  Documentation URL for this error's `code`.

• details

  (Optional)

  Structured, non-sensitive diagnostics — accepted auth modes, which credential headers were present, configured key *names*, JWT header fields. Never key values or token payloads.

• status

  (Required)

  Always `503`. Nothing about the request is wrong; the pool has no connection for it yet.

Examples

Answering 503 with a Retry-After header

import { PostgresPoolError } from '@supabase/server'

try {
  return Response.json(await ctx.postgres.query`select * from notes`)
} catch (e) {
  if (e instanceof PostgresPoolError) {
    const retryAfterMs = Number(e.details?.retryAfterMs ?? 1000)
    return Response.json(e.toJSON(), {
      status: e.status,
      headers: { 'Retry-After': String(Math.ceil(retryAfterMs / 1000)) },
    })
  }
  throw e
}