API Reference
Error Codes

Error Codes

Complete reference for NIL Taxonomy API error responses.

Error Response Format

{
  "error": "Error Type",
  "message": "Human-readable description",
  "code": "ERROR_CODE",
  "details": { ... }
}

HTTP Status Codes

200 OK

Request succeeded.

400 Bad Request

Invalid request format or parameters.

Common causes:

  • Invalid JSON in request body
  • Missing required parameters
  • Invalid parameter values

Example:

{
  "error": "Bad Request",
  "message": "Invalid license code format",
  "code": "INVALID_PARAMETER"
}

401 Unauthorized

Missing or invalid API key.

Solutions:

  • Add Authorization: Bearer <key> header
  • Verify key is correct
  • Check key hasn't expired or been revoked

Example:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Valid authentication but insufficient permissions.

Example:

{
  "error": "Forbidden",
  "message": "API key does not have access to this resource"
}

404 Not Found

Resource doesn't exist.

Example:

{
  "error": "Not Found",
  "message": "Base license 'INVALID-CODE' not found"
}

429 Too Many Requests

Rate limit exceeded.

Response:

{
  "error": "Rate limit exceeded",
  "message": "Limit of 100 requests per hour exceeded",
  "retry_after": 3600,
  "limit": 100,
  "reset_at": "2024-01-27T11:00:00Z"
}

Headers:

HTTP/1.1 429 Too Many Requests
Retry-After: 3600
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640995200

500 Internal Server Error

Server-side error.

Action: Retry after a short delay. If persists, contact support.

503 Service Unavailable

API temporarily unavailable (maintenance, etc.).

Action: Retry with exponential backoff.

Error Codes

INVALID_API_KEY

API key is malformed or doesn't exist.

Solution: Verify key format and check it exists in your account.

API_KEY_REVOKED

API key has been revoked.

Solution: Generate a new key.

API_KEY_EXPIRED

API key has passed expiration date.

Solution: Generate a new key or extend expiration.

RATE_LIMIT_EXCEEDED

Too many requests in time window.

Solutions:

  • Wait for rate limit to reset (check Retry-After header)
  • Implement request caching
  • Upgrade to higher tier

INVALID_VERSION

Requested taxonomy version doesn't exist.

Example:

{
  "error": "Invalid version",
  "message": "Taxonomy version 'v99.0' not found",
  "available_versions": ["v1.0", "v1.1"]
}

Solution: Use a valid version from available_versions.

RESOURCE_NOT_FOUND

Requested resource doesn't exist.

Example:

{
  "error": "Not Found",
  "message": "Base license 'NIL-INVALID' not found in version v1.0"
}

Solution: Check resource identifier (license code, etc.).

VALIDATION_FAILED

Request payload failed validation.

Example:

{
  "error": "Validation failed",
  "code": "VALIDATION_FAILED",
  "errors": [
    { "field": "license_code", "message": "Required field" },
    { "field": "version", "message": "Must be valid semver" }
  ]
}

Solution: Fix validation errors in request.

Retry Strategy

Exponential Backoff

For transient errors (500, 503), retry with exponential backoff:

async function fetchWithRetry(url: string, maxRetries = 3) {
  let delay = 1000; // Start with 1 second
  
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url);
      
      if (response.ok) {
        return await response.json();
      }
      
      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }
      
      // Retry server errors (5xx)
      if (i < maxRetries - 1) {
        await new Promise(resolve => setTimeout(resolve, delay));
        delay *= 2; // Exponential backoff
      }
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
  
  throw new Error('Max retries exceeded');
}

Rate Limit Handling

async function fetchWithRateLimit(url: string) {
  const response = await fetch(url);
  
  if (response.status === 429) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
    console.log(`Rate limited. Retrying in ${retryAfter}s`);
    
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return fetchWithRateLimit(url); // Retry
  }
  
  return response.json();
}

Error Handling in SDK

The SDK automatically handles retries and error formatting:

import { NILTaxonomyClient } from '@nil-taxonomy/sdk';
 
const client = new NILTaxonomyClient({
  baseUrl: process.env.NIL_TAXONOMY_API_URL!,
  apiKey: process.env.NIL_TAXONOMY_API_KEY!,
  retries: 3,           // Auto-retry on 5xx errors
  retryDelay: 1000,     // Wait 1s between retries
  timeout: 30000,       // 30s timeout
});
 
try {
  const licenses = await client.getBaseLicenses('v1');
} catch (error: any) {
  // SDK provides typed errors
  console.error('Error:', error.message);
  console.error('Status:', error.status);
  console.error('Code:', error.code);
}

Monitoring

Track Error Rates

Monitor your error rates to catch issues early:

let totalRequests = 0;
let errorCount = 0;
 
async function monitoredFetch(url: string) {
  totalRequests++;
  
  try {
    const response = await fetch(url);
    
    if (!response.ok) {
      errorCount++;
      console.warn(`Error rate: ${(errorCount / totalRequests * 100).toFixed(2)}%`);
    }
    
    return response;
  } catch (error) {
    errorCount++;
    throw error;
  }
}

Set Up Alerts

Alert when error rate exceeds threshold:

if (errorCount / totalRequests > 0.05) { // 5% error rate
  await sendAlert('High API error rate detected');
}

Support

For persistent errors:

Next Steps

AuthenticationOverview