Safe failures
Error reference
Public errors are stable codes. Detailed causes belong in redacted server logs keyed by requestId.
Wallet and policy
WALLET_NOT_FOUND means no supported wallet was detected; WRONG_NETWORK means Freighter is not using Stellar Testnet; USER_REJECTED means the person cancelled a wallet prompt; NOT_ELIGIBLE means the account does not satisfy the configured gate. Show plain guidance and let the user choose whether to retry. Do not retry a rejected wallet signature automatically.
Challenge and binding
CHALLENGE_EXPIRED means a short-lived challenge expired; CHALLENGE_SPENT means its one-use challenge or nullifier was consumed; ORIGIN_MISMATCH means the trusted host binding failed; GATE_MISMATCH means the active gate does not match; STALE_EPOCH means the credential is for an older gate epoch. Start a fresh login only when the underlying origin/gate/policy is correct. Never replay the old proof request.
Credential and verifier
CREDENTIAL_EXPIRED means proof lifetime ended; CREDENTIAL_REVOKED means the gate/credential is revoked; PROOF_INVALID means schema, root, binding, or cryptographic verification failed; SERVICE_UNAVAILABLE means a required dependency is unavailable. Retry is safe only for SERVICE_UNAVAILABLE with bounded backoff and a fresh challenge. Do not retry a revoked or invalid credential in a tight loop.
Fixture and abuse control
ASSET_TRUSTLINE_REQUIRED and ASSET_CLAIMED apply only to the optional issued-asset Testnet fixture. RATE_LIMITED requires backoff and should not trigger immediate retry. Local SDK lifecycle errors POPUP_BLOCKED, POPUP_CLOSED, and TIMEOUT are thrown as VeilPassError values and are not HTTP verifier codes.
HTTP status and safe response
Successful challenge creation returns HTTP 201. Successful verification returns HTTP 200. The example host verifier maps trusted-origin rejection to 403, expected proof/policy rejection to 400, and dependency/capacity failures to 503. Responses use stable JSON codes and an opaque requestId; never return a stack trace, SQL/chain details, proof diagnostics, wallet address, or secrets.