Skip to main content

​
“SDK not initialized” Error

Problem: Calling fetchAd() before init() has completed. Solution: Always await the init() call before fetching ads: 
const sdk = new VelocitySDK({ publisherKey: 'YOUR_PUBLISHER_KEY' });

const initResult = await sdk.init({ publisherUserId: 'user-123' });
if (!initResult.success) {
  console.error('Init failed:', initResult.error.message);
  return;
}

// Safe to fetch ads now
const adsResult = await sdk.fetchAd({ ... });

​
Ads Not Loading

Checklist:
  • ✅ SDK initialized before calling fetchAd()
  • ✅ publisherKey is correct
  • ✅ Network connectivity available
  • ✅ prompt and aiResponse are non-empty strings
  • ✅ dimensions are positive integers
Enable Development Mode: 
const sdk = new VelocitySDK({
  publisherKey: 'YOUR_PUBLISHER_KEY',
  sdkMode: 'development'  // Returns mock ads for local testing
});
Only use sdkMode: 'development' for local testing. Remove it before deploying to production.

​
Authentication Errors

Problem: AUTH_ERROR returned from init() or fetchAd(). Solution: Verify your publisherKey is correct and active. Contact support if the issue persists. 
if (!initResult.success && initResult.error.code === 'AUTH_ERROR') {
  console.error('Invalid publisher key — check your VelocitySDK configuration');
}

​
Network / Timeout Errors

Problem: NETWORK_ERROR on slow or unreliable connections. Solution: Increase the timeout and configure retries: 
const sdk = new VelocitySDK({
  publisherKey: 'YOUR_PUBLISHER_KEY',
  timeout: 15000,  // 15 seconds
  retries: 2       // Up to 3 attempts total
});

​
No Ads Returned

Possible causes:
  • No ads available for the given context
  • prompt or aiResponse too short or generic
  • Ad unit not configured
Solution: Provide more descriptive prompt and aiResponse values for better contextual matching. The SDK will return an empty ads array — always check ads.length before rendering: 
if (adsResult.success && adsResult.data.ads.length > 0) {
  renderAd(adsResult.data.ads[0]);
} else {
  // No ads available — show fallback or hide ad space
}

​
TypeScript Type Errors

Problem: Missing types or incorrect imports. Solution: Import types directly from the SDK package: 
import { VelocitySDK, VelocitySDKError } from '@velocityio/web-sdk';
The package ships with full TypeScript definitions — no @types/ package needed.