Error Reference

All FlowGuard API errors return a JSON body with an "error" field and optionally a "message" field with more detail.

{
  "error": "Stream not found",
  "message": "No stream with id abc123 exists in the database"
}

HTTP Status Codes

Code	Meaning
`400`	Bad request — missing or invalid parameters
`401`	Authentication required — missing `x-user-address` header
`403`	Forbidden — calling wallet is not authorized for this action
`404`	Resource not found
`409`	Conflict — duplicate action or unsafe state
`500`	Internal server error

Error	Cause
`Sender and recipient are required`	Missing addresses in `POST /streams/create`
`Invalid address type`	Sender or recipient is not a P2PKH cash address
`Stream is not pending`	Fund called on a non-PENDING stream
`Stream is not active`	Claim called on a non-ACTIVE stream
`Only the stream recipient can claim funds`	Wrong wallet calling claim
`Stream is not cancelable`	Cancelable flag was `false` at creation
`Only sender can cancel`	Wrong wallet calling cancel
`Unsafe cancel destination`	Contract sender hash resolves to different address than signer — pass `"allowUnsafeRecovery": true` to override
`Transaction hash not found on chipnet`	`txHash` not yet confirmed or wrong network
`Funding transaction does not include the expected contract output`	Transaction sent to wrong address or insufficient amount

Error	Cause
`Campaign is not active`	Status is PENDING, PAUSED, or CANCELLED
`Claim limit reached for this address`	`maxClaimsPerAddress` exceeded
`Address not eligible for this airdrop`	Address not in merkle tree (KYC campaign)
`Merkle tree not generated yet`	KYC campaign must generate merkle before funding
`Only the campaign creator can pause`	Wrong wallet

Error	Cause
`Invalid payment interval`	Must be DAILY, WEEKLY, BIWEEKLY, MONTHLY, or YEARLY
`Only active payments can be paused`	Status is not ACTIVE
`Only paused payments can be resumed`	Status is not PAUSED
`Payment is already cancelled`	Cannot cancel twice

Error	Cause
`Exactly 3 signers are required`	Vault creation requires exactly 3 signers
`Exactly 3 signer public keys are required`	Missing pubkeys for covenant deployment
`Only the vault creator can deposit funds`	Non-creator calling deposit
`Initial vault funding transaction must include a mutable state NFT`	Missing NFT on first deposit

Error	Cause
`Proposal must be approved before execution signing`	Not enough approvals yet
`Only vault signers can participate in payout execution signing`	Non-signer calling execute
`At least two signer keys are required`	Only one signer available in the vault
`Proposal creation transaction does not include the expected covenant NFT output`	ProposalCovenant not funded correctly

Error	Cause
`Voting period has ended`	Vote lock attempted after `votingEndsAt`
`Already voted on this proposal`	Duplicate off-chain vote from same address
`Vote lock contract data not recorded`	Unlock attempted without a prior confirmed lock
`Unlock transaction does not include expected voter token return output`	Wrong transaction submitted for unlock confirmation