Error Handling

This guide covers common errors and how to handle them.

HTTP Status Codes

Code	Meaning
200	Success
201	Created
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid API key
403	Forbidden - Not allowed to access resource
404	Not Found - Resource doesn't exist
429	Rate Limited - Too many requests
500	Server Error - Something went wrong

Error Response Format

{
  "statusCode": 400,
  "message": "Order ID \"order-123\" already exists for this merchant",
  "error": "Bad Request"
}

Common Errors

Authentication Errors

Invalid API Key

{
  "statusCode": 401,
  "message": "Invalid API key or IP not allowed",
  "error": "Unauthorized"
}

Solutions:

• Verify your API key is correct

• Check if IP whitelisting is enabled

• Ensure your IP is in the whitelist

Charge Errors

Duplicate Order ID

{
  "statusCode": 400,
  "message": "Order ID \"order-123\" already exists for this merchant",
  "error": "Bad Request"
}

Solution: Use unique order IDs for each charge.

Invalid Amount

{
  "statusCode": 400,
  "message": "Invalid amount",
  "error": "Bad Request"
}

Solution: Amount must be a positive number string (e.g., "25.00").

Charge Not Found

{
  "statusCode": 404,
  "message": "Charge not found",
  "error": "Not Found"
}

Solution: Verify the charge ID exists.

Cannot Cancel Charge

{
  "statusCode": 400,
  "message": "Only pending charges can be cancelled",
  "error": "Bad Request"
}

Solution: Only charges with PENDING status can be cancelled.

Chain Errors

Unsupported Chain

{
  "statusCode": 400,
  "message": "Unsupported or inactive chain",
  "error": "Bad Request"
}

Solution: Use a chain ID from the supported chains list.

Clone Already Deployed

{
  "statusCode": 400,
  "message": "Clone already deployed for this charge",
  "error": "Bad Request"
}

Solution: Chain can only be selected once per charge.

Handling Errors in Code

JavaScript/TypeScript

async function createCharge(orderId: string, amount: string) {
  try {
    const response = await fetch('https://api.bedrock.io/v1/charges', {
      method: 'POST',
      headers: {
        'X-API-Key': process.env.BEDROCK_API_KEY!,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ orderId, amount }),
    });

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 400:
          if (error.message.includes('already exists')) {
            throw new Error('Order already has a payment');
          }
          throw new Error('Invalid request: ' + error.message);

        case 401:
          throw new Error('API key is invalid');

        case 429:
          throw new Error('Too many requests, please retry later');

        default:
          throw new Error('Payment service error');
      }
    }

    return await response.json();
  } catch (error) {
    console.error('Failed to create charge:', error);
    throw error;
  }
}

Python

import requests

def create_charge(order_id: str, amount: str):
    try:
        response = requests.post(
            'https://api.bedrock.io/v1/charges',
            headers={
                'X-API-Key': os.environ['BEDROCK_API_KEY'],
                'Content-Type': 'application/json',
            },
            json={'orderId': order_id, 'amount': amount},
        )

        if response.status_code == 400:
            error = response.json()
            if 'already exists' in error.get('message', ''):
                raise ValueError('Order already has a payment')
            raise ValueError(f"Invalid request: {error.get('message')}")

        if response.status_code == 401:
            raise PermissionError('API key is invalid')

        if response.status_code == 429:
            raise Exception('Rate limited, please retry')

        response.raise_for_status()
        return response.json()

    except requests.RequestException as e:
        print(f'Failed to create charge: {e}')
        raise

Rate Limiting

Bedrock implements rate limiting to ensure service stability.

Endpoint	Limit
Create Charge	100/minute
Get Charge	300/minute
List Charges	60/minute

When rate limited, you'll receive:

{
  "statusCode": 429,
  "message": "Too many requests",
  "error": "Too Many Requests"
}

Handling rate limits:

1. Implement exponential backoff

2. Cache responses when possible

3. Batch operations where supported

Webhook Errors

Failed Delivery

If webhook delivery fails, Bedrock retries with exponential backoff.

Common causes:

• Endpoint returned non-2xx status

• Connection timeout

• SSL/TLS errors

Solutions:

• Return 200 status quickly

• Process webhooks asynchronously

• Use valid SSL certificates

Invalid Signature

If signature verification fails:

1. Ensure you're using the raw request body

2. Verify you're using the correct webhook secret

3. Check for any middleware modifying the body