Error Handling

View as Markdown

This page covers the errors the BlockBee API returns and how to handle each one.

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, contact 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
  • Allowlist BlockBee's IPs (51.77.105.132 and 135.125.112.47) in your firewall or Cloudflare rules.

Error Response Format

When a request fails, BlockBee returns JSON with "status": "error" and an "error" field describing the problem.

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 parameter is missing
  • 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 - A transient server error. Retry the request after a short delay.
  • No payment options available or No payment options for this value - In checkout request. No payment options exist for the requested value. Check the following:
    1. Payment Settings: Ensure you have configured your Payment Settings in your dashboard
    2. Receiving Addresses: Confirm that you have set up receiving addresses for your desired cryptocurrencies at dash.blockbee.io/profile/addresses
    3. Minimum Transaction Amounts: Check that your requested value meets the minimum transaction requirements for the selected coins. See our cryptocurrencies list for specific minimums

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
  • 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