Every Backfire error code, and how to clear it

blocked_target

blocked_target means the target resolved to an address the relay refuses to connect to: a private, loopback, link-local, multicast or cloud-metadata range on IPv4 or IPv6. Nothing was sent upstream and no trips were charged.

insufficient_trips

insufficient_trips means the account balance is at zero, so the relay refuses to start a new forward. The request is not sent upstream, nothing is logged as a completed transfer, and your keys and settings are untouched.

invalid_key

A 401 means the request had no usable Backfire key. Three codes distinguish the cases: missing_key means no Authorization header arrived, invalid_key means the value is not a live Backfire key, and key_revoked means the key existed and was revoked.

rate_limited

rate_limited means the rolling-minute allowance for the key or the account is used up. The request was not forwarded, no upstream connection was opened and no trips were charged. The ceiling exists because every forward is authorised and recorded through a row-level-security database on both legs — the key and the target on the uptrip, the response, byte counts and the balance on the downtrip. That ledger is what makes revocation effective on the next request and keeps private and metadata addresses unreachable, so the bound is published rather than discovered. Nothing else about the trip is retained: no trace log, no archived copy — it is purged the moment the roundtrip completes.

upstream_timeout

upstream_timeout means the connection to the target was made but no complete answer arrived inside the timeout. The attempt reached the network, so it is charged as a trip — the work was done.

payload_too_large

payload_too_large means the body you asked the relay to forward exceeded the per-call allowance. The request was refused before any connection was opened and no trips were charged.

response_too_large

response_too_large means the upstream answered, but the body exceeded the per-call allowance, so the relay could not hand it back as a single envelope. The attempt reached the network and is charged as a trip.

dns_failure

dns_failure means the target hostname could not be resolved, or resolved to a mixture of public and non-public addresses. Ambiguity is refused rather than guessed, and no trips are charged.

account_frozen

account_frozen means the account has been frozen as an abuse response, so forwards are refused regardless of balance. Keys, logs and settings remain readable; only new outbound calls stop.