Handle API errors gracefully

Error Handling

Learn how to handle errors returned by the API.

Error Format

All errors return a JSON object with an

text

error

field:


json
{
  "error": "Descriptive error message"
}

Error Codes

Status	Error	Cause
401	Missing API key	No API key provided
401	Invalid API key	Wrong or expired key
403	Site is inactive	Site disabled or expired
422	Invalid request	Malformed request body
429	Rate limit exceeded	Too many requests
429	Daily limit exceeded	Daily quota reached
500	AI service error	Provider unavailable

Handling Errors

Example Error Handling


javascript
async function sendMessage(message) {
  try {
    const response = await fetch('/api/chat', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-API-Key': API_KEY
      },
      body: JSON.stringify({
        message,
        session_id: SESSION_ID
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error);
    }

    return await response.json();
  } catch (err) {
    console.error('Error:', err.message);
    // Show user-friendly message
    showNotification('Failed to get response. Please try again.');
  }
}

Retry Strategy

For transient errors (500, 429), implement exponential backoff:


javascript
async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (i === maxRetries - 1) throw err;
      await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
    }
  }
}