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 are | You see | From |
|---|---|---|
| Running an agent | A thrown class such as BudgetTripped. | The SDK, before anything is signed. |
| Signing in the panel, or sending instructions yourself | A program error such as 6008 BudgetExpired. | The Breaker program. |
| Calling the HTTP API | A 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.
| Class | It means | What clears it |
|---|---|---|
PaymentTooLarge | The price is above the maxPayment you passed. | Raise maxPayment, or leave the call unpaid. |
BudgetExpired | The budget is past its expiry. | Change with a later expiry, or none. |
BudgetOff | The 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. |
BudgetTripped | The price is above what remains of this period’s limit. | The roll at resetsAt, or Reset now, or Change to a higher limit. |
InsufficientBalance | The 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
| Class | Fields |
|---|---|
PaymentTooLarge | price, maxPayment |
BudgetExpired | budget, expiredAt |
BudgetOff | budget |
BudgetTripped | budget, resetsAt, remaining, price |
InsufficientBalance | budget, 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.
| Message | It 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.
| Code | Name | It means |
|---|---|---|
| 6000 | Unauthorized | The 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. |
| 6001 | InvalidFee | A fee rate above 10,000 basis points. |
| 6002 | InvalidLabel | A label that is empty or longer than 64 bytes. |
| 6003 | InvalidLimit | A limit, or a line’s cap, of zero. |
| 6004 | InvalidPeriod | A period shorter than 60 seconds. |
| 6005 | InvalidExpiry | An expiry that is not in the future. |
| 6006 | InvalidAmount | An amount of zero, on funding, withdrawing or a channel’s deposit. |
| 6007 | InsufficientBalance | A withdrawal, or a channel’s deposit, above what the budget account holds. |
| 6008 | BudgetExpired | reset, switch_on or a channel’s open or top-up on a budget past its expiry. |
| 6009 | PeriodNotEnded | roll before the period’s end. |
| 6010 | SameAgentKey | rotate_key to the key the budget already names. |
| 6011 | InvalidAllowance | The allowance on the budget account is above what the program last approved. |
| 6012 | ArithmeticOverflow | An amount or a counter passed its largest value. |
| 6013 | BudgetOff | A channel’s open or top-up on a budget that is switched off. |
| 6014 | OverLimit | A channel’s deposit above what remains of this period’s limit. |
| 6015 | ChannelMismatch | A channel, a payer or a rent payer that is not the one the budget’s record names. |
| 6016 | ChannelNotOpen | distribute_channel on a channel the channel program no longer holds. Use close_channel. |
| 6017 | ChannelStillOpen | close_channel on a channel that has not been distributed. |
| 6018 | ChannelsOpen | close_budget while the budget has a channel open, or without its Channels address; the first set_line while a channel is open. |
| 6019 | NoLine | A 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. |
| 6020 | LineOverCap | A channel’s deposit above what the line may still take this period. |
| 6021 | LinesSet | close_budget while the budget has a line. Remove them first. |
| 6022 | InvalidRoles | Roles 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 } }
| Status | Code | It means |
|---|---|---|
| 401 | INVALID_AGENT_SIGNATURE | A report’s proof does not verify against the agent key it names. |
| 403 | AGENT_KEY_MISMATCH | A report signed by a key that is not the budget’s agent key. |
| 404 | PANEL_NOT_FOUND, BUDGET_NOT_FOUND, TRANSACTION_NOT_FOUND | No such panel, budget or submitted transaction. |
| 404 | LINE_NOT_FOUND | Remove line for a service the budget has no line for. |
| 404 | MEMBER_NOT_FOUND, PROPOSAL_NOT_FOUND | Change roles or Remove member for a wallet that is not a member; Approve or Execute for a multisig or proposal that does not exist. |
| 409 | MEMBER_ALREADY_EXISTS | Add member for a wallet that is a member already. |
| 409 | PANEL_ALREADY_EXISTS, BUDGET_ALREADY_EXISTS | The wallet has its panel, or the panel has a budget opened with this key. |
| 409 | BUDGET_CLOSED | A control on a budget that was closed. |
| 409 | BUDGET_TRIPPED, BUDGET_OFF, BUDGET_EXPIRED | The control does not apply to the budget in this state. |
| 409 | CHANNELS_OPEN | Close, 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. |
| 422 | INSUFFICIENT_BALANCE | An amount above what the wallet or the budget account holds. |
The endpoints are on the API page.