nthbouncer
Log inGet started

Understand admission errors

Symptom

Your client receives an error from ‹pool›.nthpool.cloud (or your custom domain) with an nthbouncer error body, often before any upstream latency.

Common statuses

401 unauthorized

Missing or invalid pool key, JWT, Cloudflare Access token, HMAC signature, or a replayed nonce. Fix credentials and signing clocks (±300s). Auth failures never take a concurrency slot.

403

IP allowlist rejection, or the pool's custom-hostname lock is on and you called the canonical *.nthpool.cloud host.

400

Origin selection failed. Send a valid X-Nthpool-Origin that exactly matches a configured origin, or ensure the path matches a configured path prefix.

413 payload_too_large

The body exceeds a size limit for bodies that must be fully read to verify or sign:

  • Inbound HMAC (Require signed requests): the full body must fit in 10 MB.
  • Origin verification without a usable Content-Length: the pool cannot bind length for a streamed body over 10 MB. With a correct Content-Length, origin verification prefix-signs the first 1 MB and streams the rest (no size-based 413).

Shrink the payload, send Content-Length on large origin-verified uploads, or disable the relevant signing feature for that path.

429 too_many_requests

The request never entered an open wait: the pool queue is already full, the caller set X-Nthpool-No-Queue, or the RPM gate is overloaded. Honor Retry-After when present. Raise queue depth / concurrency only within plan limits, or shed load at the client.

504 queue_timeout

The open wait ran out before a slot freed. Body message: Pool queue timeout: no slot available within the wait budget. Raise queue timeout, raise concurrency, or lower load.

504 request_timeout

The request held a slot past the request timeout. Body message: Pool request timeout: exceeded the slot lease. Raise it if the upstream call is slow, or fix hung upstream work. Both timeout responses include x-nthpool-* governor headers (total-ms, slot/queue stats) so you can tell them apart from a Cloudflare HTML 524.

503 pool_suspended

Billing or policy suspension. Check Billing and pool status in the dashboard.

501 pool_not_configured

The pool is not configured yet. Re-save the pool in the dashboard or wait a moment after create.

What to check

  1. Pool Access settings vs the headers you send
  2. Concurrency / RPM settings and current live status on the pool page
  3. Access Logs for the reject reason and timing fields
  4. Whether you intended proxy vs lock API

See also