Error Handling

View as Markdown

When you make a request to the BlockBee API, things can sometimes go wrong. This guide will help you understand the errors you might encounter and how to handle them gracefully.

Common Issues and Solutions

Funds Stuck in Address

Issue: Funds appear to be stuck in a cryptocurrency address and aren't being processed.

Possible Causes:

  • Wrong cryptocurrency sent to the address. Eg. requested funds with bep20/usdt ticker and sent bep20/usdc
  • Wrong network (e.g., sending ERC-20 tokens to BSC address)
  • Minimum transaction amount not met

Solutions:

  • Check if the address is valid for the specific cryptocurrency
  • Verify the minimum transaction amount for the cryptocurrency
  • If the wrong cryptocurrency was sent to the address and got stuck please contact our support.

Transaction Not Confirmed

Issue: Transaction is sent but remains unconfirmed for an extended period.

Possible Causes:

  • Network congestion
  • Transaction stuck in mempool

Solutions:

  • Wait for network confirmation (can take 1-24 hours depending on the network)
  • Check transaction status using the blockchain explorer

API Key Issues

Issue: API requests failing with authentication errors.

Possible Causes:

  • Missing or wrong API key in request
  • Account suspended or deactivated

Solutions:

  • Verify your API key in the BlockBee Dashboard
  • Ensure API key is included in all requests (as parameter or header)
  • Check if your account is active and in good standing
  • Generate a new API key if necessary

Callback URL Problems

Issue: Webhook notifications not being received.

Possible Causes:

  • Invalid or inaccessible callback URL
  • Server not responding to webhook requests
  • Firewall blocking incoming requests
  • SSL certificate issues

Solutions:

  • Ensure callback URL is publicly accessible
  • Test the URL manually to verify it responds
  • Check server logs for incoming webhook requests
  • Verify SSL certificate is valid (for HTTPS URLs)
  • Make sure your webhook signature verification is working
  • Add our IPs 51.77.105.132 and 135.125.112.47 to your firewall (or Cloudflare) whitelist

By understanding these common errors and issues, you can build more robust integrations and handle problems more effectively.

Error Response Format

If an API request fails, BlockBee returns an error response in JSON format. The response will always include a status field with a value of error and an error field containing a descriptive message.

JSON
{
  "status": "error",
  "error": "API Key not provided"
}

Common Errors

Here are the most common errors organized by HTTP status codes:

HTTP Status Code: 400 (Bad Request)

  • Non multi_token address already created for another token - In ticker create when you try creating an address with the same callback URL for a different ticker without multi_token parameter enabled
  • Callback URL malformed, please provide a correct URL - In ticker create endpoint when the callback parameter isn't valid
  • You must provide a valid address - In ticker create when the address provided in the address parameter is not valid
  • Maximum 20 output addresses - In ticker create when the amount of addresses provided in the address parameter exceeds 20
  • You must provide a valid address and a callback - In ticker create when you didn't provide an address and a callback parameter
  • Coin not available - Used in payout API when requested coin is not available
  • No data or data malformed - Used in payout views when request data is invalid
  • No notify url specified - Used in checkout deposit views when notification URL is missing
  • Invalid ticker - The specified {ticker} is not supported or does not exist. More information about tickers here
  • Missing value - In checkout request, the value, is missing from your request
  • Address is invalid - The provided cryptocurrency address is not valid for the specified network
  • Callback URL is not a valid URL - In the ticker create, the URL you provided in the callback parameter is not a valid, publicly accessible URL
  • Address belongs to BlockBee - You are trying to send a payout to one of your own deposit addresses
  • Your request couldn't be processed, please try again later - Your request couldn't be processed, please try again later

HTTP Status Code: 401 (Unauthorized)

  • KYC Required to use this feature - Used when KYC verification is required
  • Your KYC tier is insufficient to use this feature - Used when user's KYC level is too low
  • API Key not provided, please use api.cryptapi.io if you don't have an API key - Used when API key is missing
  • API Key not valid, please confirm your API key - Used when API key is invalid or missing

HTTP Status Code: 403 (Forbidden)

  • Merchant account deactivated - Used when user account is inactive

HTTP Status Code: 404 (Not Found)

  • Resource not found - General 404 error
  • Invoice not found - Used when invoice doesn't exist
  • Callback not found - When the callback provided in logs endpoint gave no results

Additional Common Errors

  • Not enough balance for payout - You do not have sufficient balance in your account to process a payout request
  • You need to configure your wallet in the dashboard - You have not set up a wallet address for the requested cryptocurrency in your settings