Error Handling

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Senior Engineer"
}

{
  "statusCode": 404,
  "message": "Job not found",
  "traceId": "4b1f0c9d2e6a47f8b3c5d7e9a1b2c3d4",
  "correlationId": "req_01HQ8XZ",
  "timestamp": "2026-08-03T10:30:00.000Z"
}

{
  "statusCode": 422,
  "message": "Flow validation failed",
  "errors": [
    { "path": "sections[0].blocks[2]", "message": "Question block has no text" }
  ],
  "traceId": "4b1f0c9d2e6a47f8b3c5d7e9a1b2c3d4",
  "timestamp": "2026-08-03T10:30:00.000Z"
}

class InstaViewClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseURL = 'https://api.instaview.sk/v1';
  }
  
  async request(method, path, data = null) {
    const response = await fetch(`${this.baseURL}${path}`, {
      method,
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: data ? JSON.stringify(data) : null,
      signal: AbortSignal.timeout(10_000)
    });
    
    if (!response.ok) {
      const body = await response.json().catch(() => ({}));
      return this.handleError(body, response.status, response.headers);
    }
    
    return await response.json();
  }
  
  handleError(body, statusCode, headers) {
    const error = new InstaViewError(body, statusCode);
    
    switch (statusCode) {
      case 401:
        // The key is not usable: revoked, expired, suspended, or outside its IP allowlist.
        // Retrying will not help — stop and raise it with whoever owns the key.
        console.error('Authentication failed:', error.message);
        throw error;
        
      case 403:
        // Usually a missing scope; the message names the scopes the route needed.
        console.error('Permission denied:', error.message);
        throw error;
        
      case 400:
      case 422:
        // `errors` holds one entry per rejected constraint, already written for a human.
        console.error('Rejected:', error.errors);
        throw error;
        
      case 429:
        console.log(`Rate limited. Retry after ${headers.get('Retry-After')}s`);
        throw error;
        
      case 404:
        console.warn(`${path} not found`);
        return null; // Handle gracefully
        
      case 402:
        // No active subscription, or no balance left.
        console.error('Billing:', error.message);
        throw error;
        
      default:
        console.error(`Unexpected ${statusCode}:`, error.message, error.traceId);
        throw error;
    }
  }
}

async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1000) {
  let lastError;
  
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      lastError = error;
      
      // A rate limit is the one 4xx worth retrying, and it tells you how long to wait.
      if (error.statusCode === 429) {
        await sleep(error.retryAfter ? error.retryAfter * 1000 : baseDelay);
        continue;
      }
      
      // Every other 4xx is a problem with the request itself. Sending it again
      // unchanged produces the same answer.
      if (error.statusCode >= 400 && error.statusCode < 500) {
        throw error;
      }
      
      // Server errors and timeouts: back off and try again.
      const delay = baseDelay * Math.pow(2, attempt);
      console.log(`Attempt ${attempt + 1} failed. Retrying in ${delay}ms...`);
      await sleep(delay);
    }
  }
  
  throw lastError;
}

// Usage
const job = await retryWithBackoff(async () => {
  return await client.createJob(jobData);
});

// The messages are prose, so match on the field rather than parsing them.
const FIELDS = ['email', 'phoneNumber', 'jobId', 'firstName', 'lastName'];
const FIELD_OF = (message) =>
  FIELDS.find((field) => message.toLowerCase().includes(field.toLowerCase()));

async function createContactWithValidation(contactData) {
  try {
    return await client.createContact(contactData);
  } catch (error) {
    if (error.statusCode === 400 && error.errors.length > 0) {
      for (const message of error.errors) {
        showFieldError(FIELD_OF(message), message);
      }
      
      return { success: false, errors: error.errors };
    }
    
    throw error;
  }
}

function showFieldError(field, message) {
  // Display error next to form field
  const target = document.getElementById(`${field}-error`);
  if (target) {
    target.textContent = message;
  }
}

// Both calls go through a helper that bounds the request and refuses to treat an error body
// as a result — a lookup that silently "found nothing" because it read a 403 would send the
// second call this function exists to prevent.
async function apiJson(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      Authorization: `Bearer ${apiKey}`,
      ...options.headers,
    },
    signal: options.signal ?? AbortSignal.timeout(10_000),
  });

  if (!response.ok) {
    const body = await response.json().catch(() => ({}));
    throw new InstaViewError(body, response.status);
  }

  return await response.json();
}

// Create a conversation at most once, keyed on something of your own.
async function createConversationOnce(externalId, body) {
  const existing = await apiJson(
    `https://api.instaview.sk/conversations?contactId=${body.contactId}`,
  );

  const already = existing.data.find((c) => c.metadata?.externalId === externalId);
  if (already) return already;

  return await apiJson("https://api.instaview.sk/conversations", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ ...body, metadata: { ...body.metadata, externalId } }),
  });
}

class ErrorLogger {
  static log(error, context = {}) {
    const errorLog = {
      timestamp: new Date().toISOString(),
      statusCode: error.statusCode,
      message: error.message,
      errors: error.errors,
      // The id we need to find your request in our logs.
      traceId: error.traceId,
      context: context,
      stack: error.stack
    };
    
    // Send to logging service
    console.error(JSON.stringify(errorLog));
    
    // Send to error tracking (Sentry, etc.)
    if (process.env.NODE_ENV === 'production') {
      Sentry.captureException(error, {
        extra: errorLog
      });
    }
  }
}

// Usage
try {
  await createJob(jobData);
} catch (error) {
  ErrorLogger.log(error, {
    operation: 'createJob',
    jobData: jobData,
    userId: currentUser.id
  });
  throw error;
}