Error format
Errors are returned with an HTTP status and a JSON body. Branch oncode, which is stable; message is for people and may change.
{
"error": {
"code": "quote_drifted",
"message": "…",
"details": {},
"retryAfterMs": 1200
}
}
details is included when there is something to act on, such as the quoted and current amounts of a drifted quote. retryAfterMs is included on 429 responses.
A request that fails validation, such as a missing field or an unknown chain key, returns 400 with the code invalid_request. details.issues lists each problem: in is where it was (json, query or param), path is the field, and message says what is wrong.
{
"error": {
"code": "invalid_request",
"message": "Invalid request: amountAtomic: Invalid input: expected string, received undefined",
"details": {
"issues": [
{ "in": "json", "path": "amountAtomic", "message": "Invalid input: expected string, received undefined" }
]
}
}
}
Error codes
Quote
| Code | Status | Meaning and what to do |
|---|---|---|
unknown_asset | 400 | No venue lists that token on this chain. Check the symbol or address. |
sender_required | 400 | Send the sender wallet. |
recipient_required | 400 | Send recipient. It is required when the destination chain uses a different address format from the source chain. |
invalid_sender, invalid_recipient | 400 | The address is not valid on the source or destination chain. |
invalid_refund_address | 400 | refundAddress is not valid on the source chain. |
invalid_referral | 400 | Send referralWallet and referralBps together, or neither. |
invalid_referral_wallet | 400 | referralWallet is not valid on the source chain. |
invalid_referral_bps | 400 | referralBps must be from 0 to 15. |
Build
| Code | Status | Meaning and what to do |
|---|---|---|
decision_not_found | 404 | The decisionId expired or never existed. Get a new quote. |
quote_expired, quote_drifted | 409 | The quote is too old, or the price moved too far when it was checked again. details has both amounts. Get a new quote. |
quote_not_in_decision, venue_not_in_decision | 400 | The quoteId or venue you passed is not part of this quote. |
unknown_venue | 400 | No venue has that id. |
venue_not_eligible, not_executable | 409 | The quote you chose cannot be built, for example because a wallet cannot sign it. Pick another quote. |
venue_disabled | 409 | The venue has been switched off since you quoted. Get a new quote. |
venue_not_buildable | 409 | The venue could not build this route. Pick another quote. |
privacy_venue_required | 409 | The quote was private and the venue you chose is not a private venue. |
below_min | 409 | The deposit would credit less than Hyperliquid’s minimum. |
indicative_decision | 409 | The quote was requested with indicative: true and cannot be built. |
blockhash_unavailable | 503 | BRDG could not get a recent Solana blockhash. Get a new quote and try again. |
Submit
| Code | Status | Meaning and what to do |
|---|---|---|
transfer_not_found | 404 | No transfer has that id. |
built_mismatch | 400 | The signed transaction is not what BRDG built. Nothing was sent. |
invalid_tx_hash | 400 | The hash is not valid for the source chain. |
build_expired, transfer_not_signable | 409 | The build expired before it was submitted. Build again, then sign. |
tx_not_found | 409 | The transaction is not visible on chain yet. Retry with the same hash. |
tx_reverted | 409 | The transaction matched a built step but reverted on chain. Sign again. |
tx_mismatch | 409 | That hash is on chain but is not a transaction BRDG built. Do not sign again. |
tx_hash_already_claimed | 409 | Another transfer already uses that transaction. |
user_ip_mismatch | 409 | The userIp on submit is not the one the venue created the order for. Submit from the same end user. |
broadcast_failed | 502 | The network did not accept the transaction. The transfer is unchanged, so you can sign and submit again. |
Fast fill
| Code | Status | Meaning and what to do |
|---|---|---|
fast_fill_not_private | 400 | A fast fill is never private. Drop privacy: true. |
fast_fill_unsupported_corridor | 400 | Fast fill does not reach this destination. Use POST /bridge/quote. |
not_fast_fill | 409 | The quote or transfer is not a fast fill. Use the ordinary build or submit. |
signature_mismatch | 400 | The signature is not owner’s over the built message. Nothing was sent. |
smart_wallet_unsupported | 400 | Smart contract wallets cannot sign a fast fill yet. Use a standard wallet or the ordinary route. |
fast_fill_already_signed | 409 | The transfer already has a different signature. Submit that one again. |
submit_in_progress | 409 | Another submit for this transfer is running. Retry after retryAfterMs. |
fast_fill_refused | 409 | The venue refused the signature. Nothing was sent. Quote and build again. |
fast_fill_unknown_result | 502 | The venue did not answer and may hold the signature. Submit the same signature again. |
fast_fill_submit | 409 | Submit a fast fill’s signature to POST /fastfill/transfers/{id}/submit. |
Any endpoint
| Code | Status | Meaning and what to do |
|---|---|---|
execution_disabled | 409 | Building and submitting are temporarily switched off. Quotes still work. |
invalid_api_key | 401 | An x-brdg-api-key header was sent and the key is not recognised. Check the key, or send no header to call without one. details.contact says who issues keys. |
api_key_disabled | 401 | The partner key has been switched off. Contact @kernlog on Telegram or kernlog@print.world. |
rate_limited | 429 | Too many requests. Wait retryAfterMs before retrying. Higher limits are available on request: contact @kernlog on Telegram or kernlog@print.world (also in details.contact). See Rate limits. |
not_found | 404 | The path does not exist. Check the URL and the /v1 prefix. |