SDK Guide
Troubleshooting

Troubleshooting

Common issues and their solutions when using the NIL Taxonomy SDK.

Installation Issues

Module not found: @nil-taxonomy/sdk

Problem: Package not installed or corrupted

Solution:

# Remove and reinstall
rm -rf node_modules package-lock.json
npm install
npm install @nil-taxonomy/sdk

TypeScript errors on import

Problem: TypeScript version incompatibility

Solution:

# Ensure TypeScript >= 5.0
npm install -D typescript@^5.3.0

Authentication Issues

"Invalid API key" error

Symptoms:

Error: Unauthorized - Invalid API key

Solutions:

  1. Check key format

    # Should start with "nilk_"
echo $NIL_TAXONOMY_API_KEY

  2. Verify no extra spaces

    # Trim whitespace
NIL_TAXONOMY_API_KEY=$(echo $NIL_TAXONOMY_API_KEY | xargs)

  3. Check key status

    • Log into dashboard
    • Verify key is "active" not "revoked"

"Unauthorized" with correct key

Problem: Key not included in request

Solution:

// ✅ Include in Authorization header
const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!, // Must be set
});

Validation Issues

Validation fails with "Required field missing"

Problem: License configuration incomplete

Solution:

const result = builder.tryBuild();
 
if (!result.success) {
  console.log('Missing fields:');
  result.errors?.forEach(err => {
    console.log(`- ${err.field}: ${err.message}`);
  });
}

"Invalid enum value" error

Problem: Using value not in taxonomy

Solution:

// ❌ Invalid
builder.setCommercialScope('super_commercial'); // Doesn't exist
 
// ✅ Valid (check taxonomy dimensions)
builder.setCommercialScope('full_commercial');

Refer to Dimensions for valid values.

"Logical conflict" error

Problem: Incompatible dimension combinations

Common conflicts:

// ❌ Educational + Commercial
{
  use_type: ['educational'],
  commercial_scope: 'full_commercial' // Conflict!
}
 
// ✅ Fixed
{
  use_type: ['educational'],
  commercial_scope: 'non_commercial'
}
// ❌ Global + Country-specific
{
  territory: {
    global: true,
    countries: ['US'] // Conflict!
  }
}
 
// ✅ Fixed - Choose one
{
  territory: {
    global: true
  }
}

API Issues

Request timeout

Symptoms:

Error: Request timeout after 30000ms

Solutions:

  1. Increase timeout

    const client = new NILTaxonomyClient({
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
  timeout: 60000, // Increase to 60s
});

  2. Check network

    # Test connectivity
curl https://api.nil-taxonomy.org/api/health

Rate limit exceeded

Symptoms:

Error: Rate limit exceeded (429)

Solutions:

  1. Implement caching

    let cachedLicenses: BaseLicense[] | null = null;
 
async function getLicenses() {
  if (!cachedLicenses) {
    cachedLicenses = await client.getBaseLicenses('v1');
  }
  return cachedLicenses;
}

  2. Respect rate limit headers

    const remaining = response.headers.get('X-RateLimit-Remaining');
const reset = response.headers.get('X-RateLimit-Reset');
 
if (parseInt(remaining) < 10) {
  console.warn('Approaching rate limit');
}

  3. Upgrade tier

Build Issues

Cannot find module './dist/index.js'

Problem: SDK not built

Solution:

cd node_modules/@nil-taxonomy/sdk
npm run build

Type errors in validator

Problem: TypeScript strict mode incompatibility

Solution:

// Use type assertions if needed
const license = builder.build() as LicenseConfig;

Runtime Issues

"Cannot read property of undefined"

Problem: API response structure changed or unexpected

Solution:

// Defensive programming
const licenses = await client.getBaseLicenses('v1');
 
if (!licenses || !Array.isArray(licenses)) {
  console.error('Unexpected response format');
  return;
}
 
licenses.forEach(license => {
  if (license?.code && license?.name) {
    console.log(license.code, license.name);
  }
});

Builder returns invalid license

Problem: Not validating after building

Solution:

import { validateLicense } from '@nil-taxonomy/sdk';
 
const license = builder.build();
 
// ALWAYS validate
const result = validateLicense(license);
if (!result.valid) {
  throw new Error(`Invalid license: ${result.errors}`);
}

Environment-Specific Issues

Works locally, fails in production

Problem: Environment variables not set in production

Solution:

  1. Vercel:

    • Settings → Environment Variables
    • Add NIL_TAXONOMY_API_KEY

  2. Docker:

    ENV NIL_TAXONOMY_API_KEY=nilk_xxxxx

  3. Kubernetes:

    env:
  - name: NIL_TAXONOMY_API_KEY
    valueFrom:
      secretKeyRef:
        name: nil-secrets
        key: api-key

CORS errors in browser

Problem: Making API requests from browser

🚫

Never expose API keys in client-side code. Always proxy through your backend.

Solution:

// ❌ Browser (exposes key)
const client = new NILTaxonomyClient({ apiKey: 'nilk_...' });
 
// ✅ Server-side API route
// app/api/taxonomy/route.ts
export async function GET() {
  const client = new NILTaxonomyClient({
    apiKey: process.env.NIL_TAXONOMY_API_KEY!, // Server-side
  });
  const data = await client.getBaseLicenses('v1');
  return Response.json(data);
}

Performance Issues

Slow API responses

Solutions:

  1. Cache taxonomy data

    // Taxonomy rarely changes - cache for hours
const cache = new Map();
const CACHE_TTL = 3600000; // 1 hour

  2. Batch requests

    // Fetch multiple resources in parallel
const [dimensions, licenses] = await Promise.all([
  client.getDimensions('v1'),
  client.getBaseLicenses('v1'),
]);

  3. Use CDN caching

    • API responses include Cache-Control headers
    • Configure your CDN to respect them

Getting Help

Check Status Page

https://status.nil-taxonomy.org (opens in a new tab)

Search Issues

GitHub Issues: https://github.com/nil-taxonomy/sdk/issues (opens in a new tab)

Contact Support

Email: support@nil-taxonomy.org

Include:

  • SDK version
  • Error message
  • Stack trace
  • Request ID (if available)
  • Steps to reproduce

Next Steps

ExamplesEndpoints