Skip to main content

API Error Codes

Reference for API error responses and troubleshooting.

Error Response Format​

All errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description",
    "details": {
      "field": "Additional context"
    }
  }
}

HTTP Status Codes​

StatusDescription
400Bad Request - Invalid parameters
401Unauthorized - Authentication failed
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Too Many Requests - Rate limited
500Internal Error - Server issue
503Service Unavailable - Temporary outage

Authentication Errors​

UNAUTHORIZED​

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

Causes:

  • Missing Authorization header
  • Invalid API key
  • Revoked API key
  • Expired key

Solutions:

  • Check API key is correct
  • Verify header format: Authorization: Bearer YOUR_KEY
  • Generate a new key if revoked

FORBIDDEN​

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You don't have permission to access this resource"
  }
}

Causes:

  • API key lacks required permissions
  • Not a team member
  • Chatbot not shared with you

Solutions:

  • Use a key with appropriate permissions
  • Request access from owner
  • Check team membership

Resource Errors​

NOT_FOUND​

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Chatbot not found",
    "details": {
      "chatbotId": "cb_invalid"
    }
  }
}

Causes:

  • Resource doesn't exist
  • Resource was deleted
  • Incorrect ID

Solutions:

  • Verify the resource ID
  • List resources to find correct ID
  • Check if resource was deleted

ALREADY_EXISTS​

{
  "error": {
    "code": "ALREADY_EXISTS",
    "message": "A resource with this name already exists"
  }
}

Causes:

  • Duplicate name
  • Unique constraint violation

Solutions:

  • Use a different name
  • Update existing resource instead

Validation Errors​

INVALID_REQUEST​

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Invalid request body",
    "details": {
      "message": "Field is required"
    }
  }
}

Causes:

  • Missing required field
  • Invalid field value
  • Malformed JSON

Solutions:

  • Check required fields
  • Validate field values
  • Verify JSON syntax

INVALID_FILE​

{
  "error": {
    "code": "INVALID_FILE",
    "message": "File type not supported",
    "details": {
      "supportedTypes": ["pdf", "docx", "txt"]
    }
  }
}

Causes:

  • Unsupported file type
  • File too large
  • Corrupted file

Solutions:

  • Check supported file types
  • Reduce file size
  • Try a different file

Rate Limiting​

RATE_LIMIT_EXCEEDED​

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": {
      "limit": 60,
      "remaining": 0,
      "resetAt": "2024-02-01T10:01:00Z"
    }
  }
}

Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706781660

Solutions:

  • Wait for rate limit reset
  • Implement request throttling
  • Upgrade plan for higher limits

Usage Errors​

QUOTA_EXCEEDED​

{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Monthly query limit exceeded",
    "details": {
      "limit": 1000,
      "used": 1000
    }
  }
}

Solutions:

  • Wait for billing cycle reset
  • Purchase additional credits
  • Upgrade your plan

STORAGE_LIMIT​

{
  "error": {
    "code": "STORAGE_LIMIT",
    "message": "Storage limit reached",
    "details": {
      "limit": "500MB",
      "used": "500MB"
    }
  }
}

Solutions:

  • Delete unused documents
  • Upgrade your plan

Server Errors​

INTERNAL_ERROR​

{
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An unexpected error occurred"
  }
}

Solutions:

  • Retry the request
  • Check status page
  • Contact support if persistent

SERVICE_UNAVAILABLE​

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}

Solutions:

  • Wait and retry
  • Check status page
  • Implement retry with backoff

Error Handling Best Practices​

Retry Logic​

async function apiCall(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status >= 500) {
        await sleep(Math.pow(2, i) * 1000);
        continue;
      }
      throw error;
    }
  }
}

Error Logging​

Log errors with context for debugging:

try {
  const response = await api.query(chatbotId, message);
} catch (error) {
  console.error('API Error:', {
    code: error.code,
    message: error.message,
    chatbotId,
    timestamp: new Date().toISOString()
  });
}