Error Reference

Error Codes

Complete reference of API error codes and how to handle them.

Error Response Format

All errors follow a consistent JSON structure:

error-response.json

{
  "error": {
    "code": "INVOICE_NOT_FOUND",
    "message": "Invoice with ID 'inv_123' not found",
    "details": {
      "invoiceId": "inv_123"
    }
  },
  "requestId": "req_abc123xyz"
}

code

Machine-readable error code

message

Human-readable description

requestId

Unique request identifier

HTTP Status Codes

200

Request successful

201

Created

Resource successfully created (e.g., new invoice)

400

Bad Request

Invalid request parameters or malformed JSON

401

Unauthorized

Missing or invalid API key

403

Forbidden

API key lacks required permissions

404

Not Found

Resource doesn't exist

429

Too Many Requests

Rate limit exceeded

500

Internal Server Error

Server error - contact support with requestId

Common Error Codes

Authentication Errors

INVALID_API_KEY401

The provided API key is invalid or has been revoked.

Solution: Verify your API key is correct and active

MISSING_API_KEY401

Authorization header is missing.

Solution: Include Authorization: Bearer YOUR_API_KEY header

INSUFFICIENT_PERMISSIONS403

API key doesn't have required permissions for this operation.

Solution: Use an API key with appropriate permissions

Validation Errors

INVALID_AMOUNT400

Amount is invalid, negative, or has too many decimal places.

Solution: Use positive numbers with max 2 decimal places

INVALID_ADDRESS400

Wallet address is not a valid BSC address.

Solution: Provide a valid BEP-20 wallet address

MISSING_REQUIRED_FIELD400

Required field is missing from request body.

Solution: Check API documentation for required fields

Resource Errors

INVOICE_NOT_FOUND404

Invoice with specified ID doesn't exist or doesn't belong to your tenant.

Solution: Verify the invoice ID is correct

PAYOUT_NOT_FOUND404

Payout with specified ID doesn't exist.

Solution: Verify the payout ID is correct

WEBHOOK_NOT_FOUND404

Webhook endpoint with specified ID doesn't exist.

Solution: Verify the webhook endpoint ID

Rate Limiting

RATE_LIMIT_EXCEEDED429

Too many requests. Rate limit exceeded.

Solution: Wait for Retry-After seconds before retrying

Error Handling Example

error-handling.js

async function createInvoice(data) {
  try {
    const response = await fetch('https://api.fromchain.io/v1/invoices', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.FROMCHAIN_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify(data),
    });

    if (!response.ok) {
      const error = await response.json();
      
      // Handle specific error codes
      switch (error.error.code) {
        case 'INVALID_API_KEY':
          console.error('API key is invalid. Check your configuration.');
          throw new Error('Authentication failed');
          
        case 'INVALID_AMOUNT':
          console.error('Amount validation failed:', error.error.message);
          throw new Error('Invalid amount provided');
          
        case 'RATE_LIMIT_EXCEEDED':
          const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
          console.warn(`Rate limited. Retry after ${retryAfter}s`);
          await new Promise(r => setTimeout(r, retryAfter * 1000));
          return createInvoice(data); // Retry
          
        case 'MISSING_REQUIRED_FIELD':
          console.error('Missing field:', error.error.details);
          throw new Error('Invalid request data');
          
        default:
          console.error('API error:', error.error.message);
          console.error('Request ID:', error.requestId);
          throw new Error(`API error: ${error.error.code}`);
      }
    }

    return await response.json();
    
  } catch (error) {
    if (error instanceof TypeError) {
      console.error('Network error:', error.message);
      throw new Error('Failed to connect to API');
    }
    throw error;
  }
}

// Usage with error handling
try {
  const invoice = await createInvoice({
    amountExpected: '100.00',
    externalId: 'order_123',
    description: 'Payment for order #123',
  });
  
  console.log('Invoice created:', invoice.id);
  console.log('Deposit address:', invoice.depositAddress);
  
} catch (error) {
  console.error('Failed to create invoice:', error.message);
  // Handle error appropriately for your application
}

Error Handling Best Practices

1. Always Check HTTP Status Codes

Don't assume success. Always check response.ok or status code.

2. Log Request IDs

Save requestId from error responses for debugging and support.

3. Implement Retry Logic

Retry transient errors (500, 429) with exponential backoff. Don't retry 4xx errors.

4. Handle Network Errors

Catch network exceptions (timeouts, DNS failures) separately from API errors.

5. Validate Before Sending

Validate data client-side to avoid unnecessary API calls and reduce 400 errors.