Error Codes

Understand and handle errors returned by the Venshack API.

Error Response Format

All API errors return a consistent JSON format:

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Wallet balance is insufficient for this transaction",
    "details": {
      "required": 5000,
      "available": 2500
    }
  },
  "requestId": "req_xyz789"
}

Error Object Fields

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Authentication Errors

Validation Errors

Vending Errors

Disco Vending Errors

Disco vending (/v1/disco-vending/*) is a separate collection from Venshack vending. Provider rejections are returned as HTTP 200 with success: false and an errorCode. When a transaction is still processing, requery it with the returned reference — do not start a new purchase.

Wallet Errors

Access Code Errors

Rate Limiting

When you exceed rate limits, you'll receive a 429 response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please retry after 60 seconds.",
    "details": {
      "retryAfter": 60,
      "limit": 100,
      "window": "1m"
    }
  }
}

Error Handling Best Practices

1. Check Error Codes, Not Messages

Error messages may change over time. Always use the code field for programmatic handling:

// ✅ Good
if (error.code === 'INSUFFICIENT_BALANCE') {
  promptUserToFundWallet();
}

// ❌ Bad  
if (error.message.includes('insufficient')) {
  promptUserToFundWallet();
}

2. Implement Retry Logic

For transient errors (5xx, DISCO_UNAVAILABLE), implement exponential backoff:

async function vendWithRetry(params, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await venshack.vend(params);
    } catch (error) {
      if (!isRetryable(error) || i === maxRetries - 1) {
        throw error;
      }
      await sleep(Math.pow(2, i) * 1000); // 1s, 2s, 4s
    }
  }
}

function isRetryable(error) {
  return error.status >= 500 || 
         error.code === 'DISCO_UNAVAILABLE';
}

3. Log Request IDs

Always log the requestId from error responses. This helps support debug issues quickly:

try {
  await venshack.vend(params);
} catch (error) {
  console.error('Vend failed', {
    code: error.code,
    message: error.message,
    requestId: error.requestId // Important for support
  });
}

4. Handle Validation Errors Gracefully

Validation errors include details about which fields failed:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "fields": [
        { "field": "meterNumber", "error": "Must be 11-13 digits" },
        { "field": "amount", "error": "Must be at least 500" }
      ]
    }
  }
}