Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.
On this page
Exit codes and errors
bouncer and bouncer-admin share one table of exit codes, so a script can read any of them the same way. It's also printed at the end of bouncer --help.
Exit 16, database_unavailable, and exit 7 for resource_not_provisioned are from 0.5.7. Check the client build as well as the server. Older clients use
their own mapping for a server code they don't know, described below.
| Code | Meaning |
|---|---|
| 0 | Done. For wait, request --wait and exec: the request was approved |
| 1 | Something went wrong: the server couldn't be reached, failed (HTTP 5xx or 429), or sent something this version can't read |
| 2 | The command line was wrong |
| 3 | The request was denied |
| 4 | The request expired without a decision |
| 5 | The request was cancelled or superseded |
| 6 | The server refused: the key wasn't accepted, the caller isn't allowed, the object doesn't exist, or the input was invalid. Also: OpenBao refused a read with the issued token |
| 7 | Configuration: no server address, no key, a key file others can read, plain HTTP to another machine, or (for bouncer-admin) an admin socket that can't be opened. From 0.5.7, also a server resource whose role-kit setup needs repair (resource_not_provisioned) |
| 8 | No active grant for the resource, including a grant that has just ended |
| 9 | The deadline passed while the request was in a state this version doesn't know |
| 10 | Revoked, but OpenBao didn't confirm the revoke of every issued token. The grant is still ended |
| 11 | bouncer-admin revoke --all wasn't confirmed (no yes, or no --yes when not on a terminal) |
| 12 | The server is running, but its vault (OpenBao) is sealed (backend_sealed). An outage, not a refusal: the server's administrator must unseal it |
| 13 | The server is running, but can't reach its vault (backend_unreachable). An outage, not a refusal |
| 14 | The server is running, but its vault refused the server's own login (backend_auth_failed). An outage, not a refusal of your key: the server's administrator must fix the server's login |
| 15 | Can't reach the server: the proxy in front of it (such as tailscale serve) answered 502, 503 or 504 with no Bouncer error, because the server didn't answer. It's down or restarting |
| 16 | From 0.5.7: the server is running, but PostgreSQL is unavailable (database_unavailable). The server's administrator must check the database |
| 126 | exec: the command was found but couldn't be started |
| 127 | exec: the command wasn't found |
Once exec has started the command, the exit code is the command's own.
bouncer-mcp uses 0 for success, 1 when it cannot start or the MCP session fails, 2 for unknown arguments, 7 for a configuration problem (such as a key that is not an agent's), and 12 to 15 as above when the server cannot serve. From 0.5.7, it also uses 16 for a database outage. Inside an MCP session, errors are returned to the agent as tool errors it can read. From 0.5.7, resource_not_provisioned makes one call and returns an error saying the server's administrator must repair it, without retrying; the matching CLI exit is 7. When Bouncer can't serve, the tool error says it isn't a denial, says what's wrong, and asks the agent to tell the person it's working for.
Codes 12 to 16 are outages, not refusals (16 is from 0.5.7). Nothing is wrong with your key or your request, so don't rotate keys or treat them as an attack. Each message says who has to act, usually the server's administrator. See When Bouncer is unavailable.
Server error codes
When the server refuses something, it answers with an application/problem+json body that has a machine-readable code. With --json, bouncer prints that body as it came. The codes a requester is most likely to see:
| Code | HTTP | Meaning | Exit code |
|---|---|---|---|
unauthenticated | 401 | No key, or not a valid one | 6 |
requester_disabled | 403 | This requester has been disabled | 6 |
forbidden | 403 | A valid key, but not allowed to do this | 6 |
not_requestable | 403 | This requester may not ask for this resource | 6 |
not_found | 404 | No such object, or not visible to this requester | 6 |
invalid_body | 400 | The request doesn't match the API | 6 |
reason_invalid | 422 | The reason is empty, too long, or has hidden characters | 6 |
duration_not_permitted | 422 | The duration isn't allowed for this resource | 6 |
request_not_pending | 409 | The request was already decided, expired or cancelled | 6 |
grant_not_active | 409 | The grant has expired, been revoked or been suspended | 8 |
idempotency_conflict | 409 | The same idempotency key was used with a different request | 6 |
rate_limited | 429 | Too many attempts; try again later | 1 |
issuance_failed | 502 | Bouncer couldn't release a credential | 1 |
write_failed | 502 | OpenBao didn't save the values | 1 |
internal | 500 | Something failed on the server; its log has the details | 1 |
backend_sealed | 503 | The server is running, but its vault (OpenBao) is sealed | 12 |
backend_unreachable | 503 | The server is running, but can't reach its vault | 13 |
backend_auth_failed | 503 | The server is running, but its vault refused the server's own login | 14 |
resource_not_provisioned | 503 | From 0.5.7: this resource needs the server's administrator to repair its role-kit token role or policy. One call, no retries | 7 |
database_unavailable | 503 | From 0.5.7: the server is running, but PostgreSQL failed its readiness probe | 16 |
| (none: a bare 502, 503 or 504) | The proxy in front of the server got no answer from it | 15 |
A code this version doesn't know is read by its HTTP status: a 4xx is 6 (except 429, which is 1), and a 5xx is 1. A 4xx answer is the server saying no (The server said no: ...); a 5xx with a Bouncer error is it failing (The server couldn't do it: ...). The HTTP API reference lists every code.
Retries
bouncer makes up to four attempts at each call: the first, and up to three retries. It waits as long as the server's Retry-After says, or else 1, 2, then 4 seconds.
- Calls that are safe to repeat (reads, revokes, filing a request and fetching a token, which carry an idempotency key) are retried on a dropped connection, a timeout, and HTTP 429, 500, 502, 503 or 504.
- Every other call is retried only on HTTP 429 or 503, or when the connection failed before anything was sent.
- Never retried: the server's
backend_sealed,backend_unreachableandbackend_auth_failed, and (from 0.5.7)resource_not_provisioned. They need the server's administrator, sobouncersays so at once rather than after a minute of retries.
From 0.5.7, database_unavailable follows the HTTP 503
retry rule, with up to four attempts per HTTP call and Retry-After: 5.
An MCP tool reports the problem to the agent and asks it to tell the person it's working for. It doesn't ask the agent to keep calling the tool.
It never follows a redirect, so a key or token can't be sent on to another host.
How this was checked
The table is from cli/src/exit.rs and cli/src/http.rs, the retries from cli/src/client.rs, and the server codes and statuses from server/src/error.rs and the contract. The fake-data operator tests saw exec --no-request exit 8 after a revoke. The other exit codes are checked against source only.
The database case (exit 16) was checked against the source at commit b6acf52, including its CLI and MCP tests. It hasn't been run in a test with a live server.