Error Codes

Comprehensive guide to ClawPay API errors and how to handle them.

Error Response Format

All API errors follow this structure:

{
  "error": {
    "type": "invalid_request_error",
    "code": "vault_not_found",
    "message": "No vault found with ID vault_123",
    "param": "vaultId",
    "requestId": "req_abc123xyz",
    "statusCode": 404
  }
}

Error Types

authentication_error

Invalid or missing API key.

Status Code: 401

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid API key provided"
  }
}

Common causes:

• Missing Authorization header

• Invalid API key format

• Expired or revoked API key

• Using test key in production

How to fix:

// Verify your API key
const client = new ClawPay({
  apiKey: process.env.CLAWPAY_API_KEY // Check this is set correctly
});

invalid_request_error

Malformed request or invalid parameters.

Status Code: 400

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_required_param",
    "message": "Missing required parameter: vaultId",
    "param": "vaultId"
  }
}

Common codes:

• missing_required_param - Required field not provided

• invalid_param_value - Parameter has invalid value

• invalid_currency - Unsupported currency

• invalid_amount - Amount format invalid

How to fix:

// Validate parameters before calling API
if (!vaultId) {
  throw new Error('vaultId is required');
}

if (amount <= 0) {
  throw new Error('amount must be positive');
}

permission_error

Insufficient permissions for the operation.

Status Code: 403

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_permissions",
    "message": "API key does not have permission to perform this action",
    "requiredPermission": "vaults:write"
  }
}

Common causes:

• Using restricted key with insufficient scope

• Attempting to access another user's resources

• Operation requires 2FA but not provided

How to fix:

// Use a key with appropriate permissions
// Or create a restricted key with correct scopes
const key = await client.keys.create({
  name: 'Vault Management',
  permissions: ['vaults:read', 'vaults:write']
});

rate_limit_error

Too many requests in a short period.

Status Code: 429

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 60 seconds",
    "retryAfter": 60,
    "limit": 600,
    "remaining": 0,
    "resetAt": "2024-01-15T15:00:00Z"
  }
}

How to handle:

async function makeRequestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.statusCode === 429) {
        const retryAfter = error.retryAfter || Math.pow(2, i) * 1000;
        console.log(`Rate limited. Retrying after ${retryAfter}ms`);
        await sleep(retryAfter);
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const vault = await makeRequestWithRetry(() =>
  client.vaults.retrieve('vault_123')
);

resource_error

Resource-specific errors.

Status Code: 404, 409, 422

{
  "error": {
    "type": "resource_error",
    "code": "vault_not_found",
    "message": "No vault found with ID vault_123",
    "resourceType": "vault",
    "resourceId": "vault_123"
  }
}

Common codes:

• vault_not_found - Vault doesn't exist

• card_not_found - Card doesn't exist

• insufficient_balance - Not enough funds

• vault_frozen - Vault is frozen

• card_cancelled - Card is cancelled

• duplicate_idempotency_key - Request already processed

How to handle:

try {
  const vault = await client.vaults.retrieve('vault_123');
} catch (error) {
  if (error.code === 'vault_not_found') {
    console.log('Vault does not exist');
    // Create new vault or use different ID
  } else if (error.code === 'insufficient_balance') {
    console.log('Not enough funds');
    // Request deposit or adjust amount
  }
}

server_error

Internal server error.

Status Code: 500, 502, 503

{
  "error": {
    "type": "server_error",
    "code": "internal_error",
    "message": "An internal error occurred. Please try again later",
    "requestId": "req_abc123xyz"
  }
}

What to do:

1. Retry the request with exponential backoff

2. If persistent, contact support with requestId

3. Check status page: useclawpay.app/status

Error Codes Reference

Authentication Errors

Code	Description	Fix
invalid_api_key	API key is invalid	Verify key is correct
expired_api_key	API key has expired	Generate new key
revoked_api_key	API key was revoked	Create new key
invalid_session	Session token expired	Re-authenticate
2fa_required	Operation needs 2FA	Complete 2FA flow

Vault Errors

Code	Description	Fix
vault_not_found	Vault doesn't exist	Check vault ID
vault_frozen	Vault is frozen	Unfreeze or contact support
vault_closed	Vault is closed	Cannot reopen, create new
insufficient_balance	Not enough funds	Deposit more funds
invalid_currency	Currency not supported	Use USDC, SOL, etc.
minimum_balance	Below minimum balance	Deposit to meet minimum

Card Errors

Code	Description	Fix
card_not_found	Card doesn't exist	Check card ID
card_frozen	Card is frozen	Unfreeze card
card_cancelled	Card is cancelled	Issue new card
card_expired	Card has expired	Issue replacement
daily_limit_exceeded	Daily spend limit hit	Wait or increase limit
monthly_limit_exceeded	Monthly limit hit	Wait or increase limit
merchant_blocked	Merchant not allowed	Update whitelist
category_blocked	Category not allowed	Update allowed categories

Transaction Errors

Code	Description	Fix
transaction_declined	Transaction declined	Check decline reason
authorization_failed	Failed authorization checks	Review policy rules
approval_required	Needs manual approval	Approve transaction
approval_timeout	Approval timed out	Retry with longer timeout
invalid_amount	Amount invalid	Check amount format
duplicate_transaction	Duplicate detected	Use different idempotency key

Transfer Errors

Code	Description	Fix
invalid_address	Blockchain address invalid	Verify address format
network_congestion	Network is congested	Retry with higher priority
transfer_failed	Transfer failed onchain	Check blockchain explorer
same_vault_transfer	Source = destination	Use different vaults

SDK Error Handling

TypeScript

import { ClawPay } from '@clawpay/sdk';

try {
  const vault = await client.vaults.retrieve('vault_123');
} catch (error) {
  if (error instanceof ClawPay.errors.NotFoundError) {
    console.error('Vault not found:', error.message);
  } else if (error instanceof ClawPay.errors.AuthenticationError) {
    console.error('Authentication failed:', error.message);
  } else if (error instanceof ClawPay.errors.RateLimitError) {
    console.error('Rate limited. Retry after:', error.retryAfter);
  } else if (error instanceof ClawPay.errors.PermissionError) {
    console.error('Insufficient permissions:', error.requiredPermission);
  } else {
    console.error('Unexpected error:', error.message);
  }
}

Python

from clawpay import ClawPay
from clawpay.errors import (
    NotFoundError,
    AuthenticationError,
    RateLimitError,
    PermissionError
)

try:
    vault = client.vaults.retrieve('vault_123')
except NotFoundError as e:
    print(f'Vault not found: {e.message}')
except AuthenticationError as e:
    print(f'Authentication failed: {e.message}')
except RateLimitError as e:
    print(f'Rate limited. Retry after: {e.retry_after}s')
except PermissionError as e:
    print(f'Insufficient permissions: {e.required_permission}')
except Exception as e:
    print(f'Unexpected error: {e}')

Go

vault, err := client.Vaults.Retrieve("vault_123")
if err != nil {
    switch e := err.(type) {
    case *clawpay.NotFoundError:
        log.Printf("Vault not found: %s", e.Message)
    case *clawpay.AuthenticationError:
        log.Printf("Authentication failed: %s", e.Message)
    case *clawpay.RateLimitError:
        log.Printf("Rate limited. Retry after %d seconds", e.RetryAfter)
    case *clawpay.PermissionError:
        log.Printf("Insufficient permissions: %s", e.RequiredPermission)
    default:
        log.Printf("Unexpected error: %v", err)
    }
}

Best Practices

1. Always Handle Errors

// Bad
const vault = await client.vaults.retrieve('vault_123');

// Good
try {
  const vault = await client.vaults.retrieve('vault_123');
} catch (error) {
  console.error('Failed to retrieve vault:', error);
  // Handle appropriately
}

2. Use Specific Error Handlers

async function getVault(vaultId: string) {
  try {
    return await client.vaults.retrieve(vaultId);
  } catch (error) {
    if (error instanceof ClawPay.errors.NotFoundError) {
      // Create vault if it doesn't exist
      return await client.vaults.create({ name: 'New Vault' });
    } else if (error instanceof ClawPay.errors.RateLimitError) {
      // Retry after delay
      await sleep(error.retryAfter * 1000);
      return getVault(vaultId);
    } else {
      // Propagate other errors
      throw error;
    }
  }
}

3. Log Request IDs

try {
  await client.vaults.retrieve('vault_123');
} catch (error) {
  console.error('Request failed:', {
    requestId: error.requestId,
    code: error.code,
    message: error.message
  });
  // Include requestId when contacting support
}

4. Implement Retry Logic

async function retryWithBackoff<T>(
  fn: () => Promise<T>,
  maxRetries = 3,
  baseDelay = 1000
): Promise<T> {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      const isRetryable =
        error instanceof ClawPay.errors.RateLimitError ||
        error instanceof ClawPay.errors.ServerError;

      if (!isRetryable || i === maxRetries - 1) {
        throw error;
      }

      const delay = error.retryAfter
        ? error.retryAfter * 1000
        : baseDelay * Math.pow(2, i);

      console.log(`Retry ${i + 1}/${maxRetries} after ${delay}ms`);
      await sleep(delay);
    }
  }
  throw new Error('Max retries exceeded');
}

// Usage
const vault = await retryWithBackoff(() =>
  client.vaults.retrieve('vault_123')
);

5. Validate Before Calling API

function validateVaultCreation(params: VaultCreateParams) {
  if (!params.name || params.name.length < 3) {
    throw new Error('Vault name must be at least 3 characters');
  }

  if (!['USDC', 'SOL'].includes(params.currency)) {
    throw new Error('Invalid currency');
  }

  if (params.initialDeposit && params.initialDeposit < 0) {
    throw new Error('Initial deposit must be positive');
  }
}

// Validate before API call
validateVaultCreation(params);
const vault = await client.vaults.create(params);

Monitoring Errors

Error Rate Tracking

class ErrorTracker {
  private errors: Map<string, number> = new Map();

  track(error: ClawPayError) {
    const key = `${error.type}:${error.code}`;
    this.errors.set(key, (this.errors.get(key) || 0) + 1);
  }

  getTopErrors(limit = 10) {
    return Array.from(this.errors.entries())
      .sort((a, b) => b[1] - a[1])
      .slice(0, limit);
  }
}

const tracker = new ErrorTracker();

try {
  await client.vaults.retrieve('vault_123');
} catch (error) {
  tracker.track(error);
  throw error;
}

Alert on Critical Errors

async function monitorErrors() {
  const metrics = await client.getErrorMetrics({
    period: '1h'
  });

  if (metrics.authenticationErrors > 10) {
    await sendAlert('High authentication error rate');
  }

  if (metrics.serverErrors > 5) {
    await sendAlert('Multiple server errors detected');
  }

  if (metrics.errorRate > 0.05) { // 5%
    await sendAlert('Error rate above threshold');
  }
}

Getting Help

If you encounter persistent errors:

1. Check Status Page: useclawpay.app/status

2. Search Documentation: docs.useclawpay.app

3. Contact Support: [email protected]

   • Include requestId from error response

   • Describe steps to reproduce

   • Include relevant code snippets

Next Steps

• API Reference

• Authentication

• Quickstart Guide

• Webhooks