# 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](/docs/pools/concurrency#queue): 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](/docs/pools/concurrency#queue) 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](/docs/pools/concurrency#timeouts). 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](/docs/api/locks)

## See also

- [Pools](/docs/pools)
- [Authentication](/docs/pools/access)
- [Concurrency](/docs/pools/concurrency)