API Error Codes

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": 4012,
  "message": "Invalid API Key."
}

curl -X GET "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

curl -X GET "https://admin.searchxengine.ai/api/v2/applications/YOUR_APP_ID?api_key=YOUR_API_KEY"

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": 4012,
  "message": "Invalid API Key."
}

✅ Correct:   /api/v2/applications/a1b2c3d4e5/search
❌ Incorrect: /api/v2/applications//search
❌ Incorrect: /api/v2/applications/invalid_id/search

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "errorCode": 4015,
  "message": "This API key has been revoked. Please regenerate or create a new key."
}

Request:  /api/v2/applications/a1b2c3d4e5/search
API Key:  Belongs to x9y8z7w6v5
Result:   403 Forbidden

# Get your app_id from the dashboard
APP_ID="YOUR_APP_ID"

# Get the API key for THAT specific application
API_KEY="YOUR_API_KEY"

curl -X POST "https://admin.searchxengine.ai/api/v2/applications/${APP_ID}/search" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"q": "shoes"}'

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": 4032,
  "message": "Origin mismatch. Expected: https://example.com, Got: https://wrong-domain.com"
}

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "errorCode": 4033,
  "message": "Application configuration error: website_origin not set. Configure origin in application settings."
}

HTTP/1.1 404 Not Found
Content-Type: application/json

{
  "errorCode": 4041,
  "message": "Resource not found."
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "message": "The feed_url field must be a valid URL.",
  "errors": {
    "feed_url": ["The feed_url field must be a valid URL."],
    "name": ["The name field must not be greater than 255 characters."]
  }
}

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

// Invalid feed type
{
  "message": "The selected feed type is invalid.",
  "errors": {
    "feed_type": ["The selected feed type is invalid."]
  }
}

// Search query too long
{
  "message": "The q field must not be greater than 500 characters.",
  "errors": {
    "q": ["The q field must not be greater than 500 characters."]
  }
}

// Invalid embedder
{
  "message": "Invalid payload.",
  "errors": {
    "hybrid.embedder": [
      "The embedder 'invalid' is not configured for this application."
    ]
  }
}

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
Retry-After: 60
Content-Type: application/json

{
  "message": "Rate limit exceeded. You can make 120 requests per minute. Please retry after 60 seconds."
}

async function apiRequest(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);

      if (response.status === 429) {
        const retryAfter = parseInt(response.headers.get('Retry-After') || '60');
        const delay = Math.min(retryAfter * 1000 * Math.pow(2, i), 60000);
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }

      return response;
    } catch (error) {
      if (i === maxRetries - 1) throw error;
    }
  }
}

class RateLimitedClient {
  constructor() {
    this.queue = [];
    this.processing = false;
    this.requestsPerMinute = 120;
    this.interval = 60000; // 1 minute
  }

  async request(url, options) {
    return new Promise((resolve, reject) => {
      this.queue.push({ url, options, resolve, reject });
      this.processQueue();
    });
  }

  async processQueue() {
    if (this.processing || this.queue.length === 0) return;

    this.processing = true;
    const item = this.queue.shift();

    try {
      const response = await fetch(item.url, item.options);
      item.resolve(response);
    } catch (error) {
      item.reject(error);
    }

    // Delay to stay under rate limit
    setTimeout(() => {
      this.processing = false;
      this.processQueue();
    }, this.interval / this.requestsPerMinute);
  }
}

const cache = new Map();

async function cachedSearch(query, ttl = 300000) {
  // 5 min TTL
  const key = `search:${query}`;
  const cached = cache.get(key);

  if (cached && Date.now() - cached.timestamp < ttl) {
    return cached.data;
  }

  const data = await fetch('/api/v2/applications/APP_ID/search', {
    method: 'POST',
    body: JSON.stringify({ q: query }),
  }).then((r) => r.json());

  cache.set(key, { data, timestamp: Date.now() });
  return data;
}

HTTP/1.1 502 Bad Gateway
Content-Type: application/json

{
  "errorCode": 5021,
  "message": "Search service error."
}

const response = await fetch('/api/v2/applications/APP_ID', {
  headers: { Authorization: `Bearer ${API_KEY}` },
});

if (!response.ok) {
  const error = await response.json();
  console.error(`API Error ${response.status}:`, error);

  switch (response.status) {
    case 401:
      // Re-authenticate or update API key
      break;
    case 403:
      // Check app_id matches API key
      break;
    case 429:
      // Implement retry with backoff
      break;
    case 422:
      // Fix validation errors
      console.error('Validation errors:', error.errors);
      break;
    default:
    // Generic error handling
  }
}

function logError(response, errorData) {
  console.error('SearchX API Error', {
    status: response.status,
    errorCode: errorData.errorCode,
    message: errorData.message,
    errors: errorData.errors,
    timestamp: new Date().toISOString(),
    url: response.url,
  });
}

async function searchWithFallback(query) {
  try {
    const response = await searchAPI(query);
    return response.hits;
  } catch (error) {
    if (error.status === 502) {
      // Search service down - return cached results
      return getCachedResults(query);
    }
    if (error.status === 429) {
      // Rate limited - show message to user
      throw new Error('Too many searches. Please wait a moment.');
    }
    throw error;
  }
}

function getUserMessage(errorCode) {
  const messages = {
    4011: 'Authentication required. Please sign in.',
    4012: 'Invalid credentials. Please check your API key.',
    4031: 'Access denied. Please verify your application settings.',
    4041: 'Resource not found.',
    429: 'Too many requests. Please try again in a moment.',
    502: 'Search is temporarily unavailable. Please try again.',
  };

  return messages[errorCode] || 'An error occurred. Please try again.';
}