Docs

Errors

Every error you can meet, by where it comes from: the SDK in the agent, the program on chain, the API over HTTP. Each with what it means and what clears it.

Where an error comes from

You areYou seeFrom
Running an agentA thrown class such as BudgetTripped.The SDK, before anything is signed.
Signing in the panel, or sending instructions yourselfA program error such as 6008 BudgetExpired.The Breaker program.
Calling the HTTP APIA JSON body with a code such as BUDGET_NOT_FOUND.The API.

SDK errors

Five classes, each exported by the package and each a subclass of Error with its own name. All five are thrown before the SDK signs, so when one is thrown no payment was made.

ClassIt meansWhat clears it
PaymentTooLargeThe price is above the maxPayment you passed.Raise maxPayment, or leave the call unpaid.
BudgetExpiredThe budget is past its expiry.Change with a later expiry, or none.
BudgetOffThe budget is switched off, or this key is no longer its agent key.Switch on, or give the agent the key the budget now names.
BudgetTrippedThe price is above what remains of this period’s limit.The roll at resetsAt, or Reset now, or Change to a higher limit.
InsufficientBalanceThe budget account holds less than the price.Fund.

The SDK checks in the order of the table and throws the first that applies.

What each carries

ClassFields
PaymentTooLargeprice, maxPayment
BudgetExpiredbudget, expiredAt
BudgetOffbudget
BudgetTrippedbudget, resetsAt, remaining, price
InsufficientBalancebudget, balance, price

Amounts are base-unit strings and times are ISO 8601 strings.

import { BudgetTripped, InsufficientBalance } from '@breaker/sdk'

try {
  await agent.fetch(url)
} catch (e) {
  if (e instanceof BudgetTripped) wait(e.resetsAt)
  else if (e instanceof InsufficientBalance) tellOwner(e.balance, e.price)
  else throw e
}

Other errors from the SDK

These are plain Errors. Each says something about the call or the service, and reads the same every time.

MessageIt means
The service does not offer an exact payment on a supported Solana network.The 402 held no price the SDK can pay: another scheme, or another chain.
No exact Solana offer matches this budget’s mint.The service prices in a token this budget does not hold, or the budget is on another network.
The budget does not exist or has been closed.The address in budget has no budget on the network read.
Agent key must be a base58 key, JSON byte array, or byte array containing a 32-byte seed or 64-byte secret key.The value passed as key is none of the forms on the Agent keys page.
apiUrl must use HTTP or HTTPS.The value passed as apiUrl is another kind of URL.

A response that is still 402 after the payment is returned as it is, for your code to read. The SDK reads the budget once more first, and throws one of the five classes if the budget changed in between.

Program errors

The program’s own errors, as a wallet or an explorer shows them. The panel checks each of these before it asks for a signature, so they are met mostly by code that builds instructions itself.

CodeNameIt means
6000UnauthorizedThe signer is not the panel’s owner or a member holding the instruction’s role, or not the program’s admin. Also a member opening a budget with funding.
6001InvalidFeeA fee rate above 10,000 basis points.
6002InvalidLabelA label that is empty or longer than 64 bytes.
6003InvalidLimitA limit, or a line’s cap, of zero.
6004InvalidPeriodA period shorter than 60 seconds.
6005InvalidExpiryAn expiry that is not in the future.
6006InvalidAmountAn amount of zero, on funding, withdrawing or a channel’s deposit.
6007InsufficientBalanceA withdrawal, or a channel’s deposit, above what the budget account holds.
6008BudgetExpiredreset, switch_on or a channel’s open or top-up on a budget past its expiry.
6009PeriodNotEndedroll before the period’s end.
6010SameAgentKeyrotate_key to the key the budget already names.
6011InvalidAllowanceThe allowance on the budget account is above what the program last approved.
6012ArithmeticOverflowAn amount or a counter passed its largest value.
6013BudgetOffA channel’s open or top-up on a budget that is switched off.
6014OverLimitA channel’s deposit above what remains of this period’s limit.
6015ChannelMismatchA channel, a payer or a rent payer that is not the one the budget’s record names.
6016ChannelNotOpendistribute_channel on a channel the channel program no longer holds. Use close_channel.
6017ChannelStillOpenclose_channel on a channel that has not been distributed.
6018ChannelsOpenclose_budget while the budget has a channel open, or without its Channels address; the first set_line while a channel is open.
6019NoLineA channel’s open or top-up on a budget on lines, to a recipient with no line, or not to one recipient at the full share.
6020LineOverCapA channel’s deposit above what the line may still take this period.
6021LinesSetclose_budget while the budget has a line. Remove them first.
6022InvalidRolesRoles other than Switch, Limits or both, or the owner’s own wallet named as a member.

From the token program

A payment is a token transfer, so a payment the chain refuses is refused by the token program. A transfer above the allowance, or above the balance, fails there with the token program’s InsufficientFunds. The SDK reads the budget before it signs, so a payment it builds does not reach that point.

API errors

Every error from the API has one shape. retryable says whether the same request can succeed later, and when a program refused a transaction, error.programError names the program and the error.

{ "error": { "code": "BUDGET_NOT_FOUND", "message": "…", "retryable": false } }
StatusCodeIt means
401INVALID_AGENT_SIGNATUREA report’s proof does not verify against the agent key it names.
403AGENT_KEY_MISMATCHA report signed by a key that is not the budget’s agent key.
404PANEL_NOT_FOUND, BUDGET_NOT_FOUND, TRANSACTION_NOT_FOUNDNo such panel, budget or submitted transaction.
404LINE_NOT_FOUNDRemove line for a service the budget has no line for.
404MEMBER_NOT_FOUND, PROPOSAL_NOT_FOUNDChange roles or Remove member for a wallet that is not a member; Approve or Execute for a multisig or proposal that does not exist.
409MEMBER_ALREADY_EXISTSAdd member for a wallet that is a member already.
409PANEL_ALREADY_EXISTS, BUDGET_ALREADY_EXISTSThe wallet has its panel, or the panel has a budget opened with this key.
409BUDGET_CLOSEDA control on a budget that was closed.
409BUDGET_TRIPPED, BUDGET_OFF, BUDGET_EXPIREDThe control does not apply to the budget in this state.
409CHANNELS_OPENClose, or the first Add line, on a budget with a channel open. Switch it off; once its channels have closed after their grace, try again.
422INSUFFICIENT_BALANCEAn amount above what the wallet or the budget account holds.

The endpoints are on the API page.