Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

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.

CodeMeaning
0Done. For wait, request --wait and exec: the request was approved
1Something went wrong: the server couldn't be reached, failed (HTTP 5xx or 429), or sent something this version can't read
2The command line was wrong
3The request was denied
4The request expired without a decision
5The request was cancelled or superseded
6The 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
7Configuration: 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)
8No active grant for the resource, including a grant that has just ended
9The deadline passed while the request was in a state this version doesn't know
10Revoked, but OpenBao didn't confirm the revoke of every issued token. The grant is still ended
11bouncer-admin revoke --all wasn't confirmed (no yes, or no --yes when not on a terminal)
12The server is running, but its vault (OpenBao) is sealed (backend_sealed). An outage, not a refusal: the server's administrator must unseal it
13The server is running, but can't reach its vault (backend_unreachable). An outage, not a refusal
14The 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
15Can'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
16From 0.5.7: the server is running, but PostgreSQL is unavailable (database_unavailable). The server's administrator must check the database
126exec: the command was found but couldn't be started
127exec: 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:

CodeHTTPMeaningExit code
unauthenticated401No key, or not a valid one6
requester_disabled403This requester has been disabled6
forbidden403A valid key, but not allowed to do this6
not_requestable403This requester may not ask for this resource6
not_found404No such object, or not visible to this requester6
invalid_body400The request doesn't match the API6
reason_invalid422The reason is empty, too long, or has hidden characters6
duration_not_permitted422The duration isn't allowed for this resource6
request_not_pending409The request was already decided, expired or cancelled6
grant_not_active409The grant has expired, been revoked or been suspended8
idempotency_conflict409The same idempotency key was used with a different request6
rate_limited429Too many attempts; try again later1
issuance_failed502Bouncer couldn't release a credential1
write_failed502OpenBao didn't save the values1
internal500Something failed on the server; its log has the details1
backend_sealed503The server is running, but its vault (OpenBao) is sealed12
backend_unreachable503The server is running, but can't reach its vault13
backend_auth_failed503The server is running, but its vault refused the server's own login14
resource_not_provisioned503From 0.5.7: this resource needs the server's administrator to repair its role-kit token role or policy. One call, no retries7
database_unavailable503From 0.5.7: the server is running, but PostgreSQL failed its readiness probe16
(none: a bare 502, 503 or 504)The proxy in front of the server got no answer from it15

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_unreachable and backend_auth_failed, and (from 0.5.7) resource_not_provisioned. They need the server's administrator, so bouncer says 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.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).