Skip to main content

​
Error Codes

This guide explains execution statuses and error classifications in Bridgfy, helping you understand and handle failed transactions in your integration.

​
Execution Statuses

Every execution moves through a lifecycle with specific statuses. Understanding these statuses is critical for building a robust integration.

​
Status Overview

StatusTypeRetryableDescription
PENDINGActiveN/ARoute resolved, preparing to execute
RUNNINGActiveN/ATransaction submitted to network
SUCCESSTerminalNoTransaction confirmed on-chain
FAILEDActiveMaybeExecution failed, may be retried automatically
DEAD_LETTERTerminalNoTerminal failure, no more retries
TOKEN_BLACKLISTEDTerminalNoToken is on security blacklist
FAILED_UNROUTABLE_MAINTerminalNoNo valid route found
FAILED_INVALID_INPUTTerminalNoInvalid request parameters
FAILED_NO_FUNDSTerminalNoInsufficient balance in account
FAILED_INSUFFICIENT_AFTER_FEESTerminalNoFees exceed deposit amount
QUOTA_EXCEEDEDTerminalNoOrganization quota limit reached

​
Status Details

​
PENDING

Meaning: Route has been resolved, execution record created, but transaction not yet submitted. What’s happening:
  • System is building the transaction
  • Calculating final fees
  • Preparing to submit to blockchain
Typical duration: A few seconds What to show users: “Processing your transfer…”

​
RUNNING

Meaning: Transaction submitted to the blockchain, waiting for confirmation. What’s happening:
  • Transaction is in the mempool or being processed
  • Awaiting block confirmation
  • Cross-chain bridging in progress
Typical duration: 30 seconds to several minutes (depends on chain congestion) What to show users: “Transfer in progress…” with transaction hash if available

​
SUCCESS

Meaning: Transaction confirmed on-chain, funds successfully bridged. This is a terminal status - the execution is complete. What to show users: “Transfer complete!” with:
  • Transaction hash (link to block explorer)
  • Amount received on destination chain
  • Completion timestamp

​
FAILED

Meaning: Execution failed, but may be retried automatically. Retryability depends on:
  • Error classification (network errors are retryable, validation errors are not)
  • Whether automatic retry limit has been reached
  • Error category
What’s tracked:
  • lastErrorCode - Specific error type
  • lastErrorCategory - Broad category
  • lastErrorMessage - Human-readable description
  • retryable - Whether retry is possible
What to show users: “Transfer failed” with error message. If retryable, “We’re automatically retrying…”

​
DEAD_LETTER

Meaning: Terminal failure - the execution cannot be retried. Common causes:
  1. Maximum retry attempts exceeded
  2. Non-retryable error occurred
  3. Manual intervention required
What to show users: “Transfer failed” with error details and support contact Next steps: Contact support or create a new deposit intent

​
TOKEN_BLACKLISTED

Meaning: The token is on Bridgfy’s security blacklist. Why this happens: The token has been flagged as:
  • Sanctioned
  • A known scam
  • Malicious contract
What to show users: “This token is not supported for security reasons” Next steps: Use a different token

​
FAILED_UNROUTABLE_MAIN

Meaning: No valid cross-chain route found for the token pair. Common causes:
  1. Token not supported by bridge providers
  2. Liquidity too low for the amount
  3. No bridges available between the chain pair
  4. Invalid token address
What to show users: “Route not available for this token pair” Next steps:
  • Try a different token
  • Try a different destination chain
  • Reduce the amount (if liquidity issue)
  • Use the simulation API before attempting deposits

​
FAILED_INVALID_INPUT

Meaning: Invalid parameters in the deposit or intent. Common causes:
  • Malformed addresses
  • Invalid chain IDs
  • Unsupported token
  • Zero or negative amounts
What to show users: “Invalid configuration” with specific error details Next steps: Fix the deposit intent configuration and try again

​
FAILED_NO_FUNDS

Meaning: Insufficient balance in the deposit address. Common causes:
  1. Deposit not yet confirmed on-chain
  2. Funds already spent in previous execution
  3. Wrong token deposited
  4. Deposit amount less than expected
What to show users: “Insufficient funds detected” Next steps: Verify the deposit transaction completed successfully

​
FAILED_INSUFFICIENT_AFTER_FEES

Meaning: After deducting fees, nothing remains to bridge. Common causes:
  • Deposit amount too small
  • Gas costs exceed deposit value
  • Protocol fee + gas fee > deposit amount
What to show users: “Deposit amount too small to cover fees” Next steps:
  • Increase deposit amount
  • Use the simulation API to determine minimum amount
  • Consider tokens with lower gas costs
Prevention: Always use the simulation API before initiating deposits to verify fees.

​
QUOTA_EXCEEDED

Meaning: Your organization has reached its monthly quota limit. Common causes:
  • Free tier limits reached
  • Monthly execution cap exceeded
  • Volume limits hit
What to show users: “Service limit reached. Please upgrade your plan.” Next steps:
  • Upgrade your organization’s plan in the Dashboard
  • Contact sales for higher limits

​
Error Classification

Bridgfy classifies errors to determine if they can be retried automatically. Understanding error categories helps you build better error handling in your application.

​
Error Categories

​
Retryable Errors

These errors are temporary and may succeed if retried:
CategoryDescriptionExample
NETWORKNetwork connectivity issuesConnection timeout, DNS failure
TIMEOUTRequest took too longProvider timeout, slow RPC
PROVIDER_5XXProvider server error500, 502, 503, 504 errors
RATE_LIMITToo many requests429 rate limit error
Automatic retry: Yes, with exponential backoff What to do: Wait for automatic retry, monitor execution status

​
Terminal Errors

These errors are permanent and cannot be fixed by retrying:
CategoryDescriptionExample
VALIDATIONInvalid inputBad address, invalid chain ID
PROVIDER_4XXClient error400, 401, 403, 404 errors
BLOCKCHAIN_REVERTTransaction revertedSmart contract rejection
TOKEN_BLACKLISTEDSecurity blockToken on blacklist
Automatic retry: No What to do: Fix the underlying issue and create a new deposit intent

​
Error Classification Flow

​
Handling Errors in Your Application

​
Check Execution Status

Query execution status regularly to track progress: 
GET /api/users/:userId/executions
x-api-key: your_api_key
Response includes:
  • status - Current execution status
  • lastErrorCode - Error type (if failed)
  • lastErrorMessage - Human-readable error
  • retryable - Whether automatic retry is possible

​
Display Appropriate Messages

Based on the status, show users: PENDING/RUNNING: 
"Processing your transfer... This may take a few minutes."
SUCCESS: 
"Transfer complete! View transaction: [link]"
FAILED (retryable): 
"Transfer temporarily failed. We're automatically retrying..."
FAILED_INSUFFICIENT_AFTER_FEES: 
"Deposit amount too small to cover fees. 
Minimum required: [amount from simulation]"
FAILED_UNROUTABLE_MAIN: 
"This token pair is not currently supported. 
Please try a different token or destination chain."
TOKEN_BLACKLISTED: 
"This token cannot be processed for security reasons."
QUOTA_EXCEEDED: 
"Your organization has reached its monthly limit. 
Please upgrade your plan to continue."

​
Implement Retry Logic

For FAILED status with retryable: true:
  1. Don’t create a new deposit - the system retries automatically
  2. Poll for status updates - Check every 10-30 seconds
  3. Set a timeout - If still failed after 10 minutes, show error
  4. Provide user updates - Show that retry is in progress

​
Use Simulation to Prevent Errors

Before initiating deposits, use the simulation API: 
POST /api/routing/simulate-deposit
This helps prevent:
  • FAILED_UNROUTABLE_MAIN - Verify route exists
  • FAILED_INSUFFICIENT_AFTER_FEES - Calculate minimum amount
  • Unexpected fees - Show users exact amounts

​
Common Scenarios

​
Scenario: Small Deposit Amount

User deposits: 1 USDC
Gas cost: 0.8 USDC
Protocol fee: 0.01 USDC Result: FAILED_INSUFFICIENT_AFTER_FEES Solution: Use simulation API to calculate minimum deposit. Show users: “Minimum deposit: 2 USDC”

​
Scenario: Unsupported Token

User deposits: Custom token 0x1234...
Routing check: No bridges support this token Result: FAILED_UNROUTABLE_MAIN Solution: Before showing deposit address, verify token is routable via simulation API

​
Scenario: Network Issue

Error: Network timeout during execution
Classification: Retryable Result: FAILED with retryable: true Action: System automatically retries. Status changes to RUNNING or SUCCESS on retry

​
Best Practices

​
For Integrators

  1. Always simulate first - Use simulation API before showing users deposit addresses
  2. Handle all statuses - Build UI for all possible execution statuses
  3. Poll for updates - Check status periodically for PENDING/RUNNING/FAILED (retryable) executions
  4. Show transaction hashes - Link to block explorers for transparency
  5. Communicate clearly - Explain errors in user-friendly language
  6. Set minimums - Use simulation to determine and enforce minimum deposit amounts
  7. Provide support links - For terminal errors, give users a way to get help

​
Error Recovery

For retryable errors:
  • Don’t create duplicate deposit intents
  • Trust the automatic retry system
  • Monitor execution status
  • Set reasonable timeouts (10-15 minutes)
For terminal errors:
  • Log error details for debugging
  • Notify users with clear next steps
  • For FAILED_INSUFFICIENT_AFTER_FEES, calculate and show required minimum
  • For FAILED_UNROUTABLE_MAIN, suggest alternative tokens or chains

​
Next Steps