RAG ChatsRAG Chats

Errors & Rate Limits

Understand API error codes and implement proper error handling in your applications.

Error Response Format

All errors are returned with a consistent JSON structure:

{
  "error": "error_code",
  "message": "Human-readable error message",
  "details": {
    // Additional context (varies by error)
  }
}

HTTP Status Codes

400 Bad RequestClient Error

Invalid request body, missing required fields, or validation error.

401 UnauthorizedClient Error

Missing or invalid authentication token.

403 ForbiddenClient Error

Valid token but insufficient permissions for this resource.

404 Not FoundClient Error

Resource not found or not accessible.

429 Too Many RequestsClient Error

Rate limit exceeded. See rate limiting section.

500 Internal Server ErrorServer Error

Unexpected server error. Contact support if persistent.

503 Service UnavailableServer Error

Service temporarily unavailable. Usually during maintenance.

Error Codes

Authentication Errors

invalid_token401

The provided token is invalid or malformed.

token_expired401

The access token has expired. Refresh it.

invalid_credentials401

Email or password is incorrect.

invalid_api_key401

API key is invalid or has been revoked.

Resource Errors

not_found404

The requested resource does not exist.

agent_not_found404

Agent ID is invalid or you don't have access.

data_source_not_found404

Data source ID is invalid or deleted.

conversation_not_found404

Conversation ID is invalid or expired.

Validation Errors

validation_error400

Request body failed validation. Check details field.

missing_field400

Required field is missing from request.

invalid_field400

Field value is invalid (wrong type, format, or range).

Rate Limit Errors

rate_limit_exceeded429

Too many requests. Wait before retrying.

quota_exceeded429

Monthly query quota reached. Upgrade plan or wait.

Service Errors

agent_not_ready503

Agent is still processing data sources. Try later.

llm_error500

Error from the AI model provider.

internal_error500

Unexpected error. Contact support.

Rate Limiting

API requests are rate limited to ensure fair usage and system stability.

Limits by User Type

User TypeRate Limit
Authenticated users1,000 requests/hour
Agent queries60 requests/minute per agent
Unauthenticated100 requests/hour

Rate Limit Headers

Every response includes rate limit information in headers:

X-RateLimit-Limit: 1000        # Maximum requests allowed
X-RateLimit-Remaining: 950     # Requests remaining in window
X-RateLimit-Reset: 1699286400  # Unix timestamp when limit resets

Rate Limit Response

{
  "error": "rate_limit_exceeded",
  "message": "Too many requests. Please retry after 32 seconds.",
  "details": {
    "retry_after": 32,
    "limit": 60,
    "window": "minute"
  }
}

Error Handling Best Practices

Implement Retry Logic

500">async 500">function queryWithRetry(agentId, message, maxRetries = 3) {
  500">let lastError;
  
  500">for (500">let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      500">const response = 500">await fetch(500">class="text-green-500">`/api/agents/${agentId}/query/`, {
        method: 500">class="text-green-500">'POST',
        headers: {
          500">class="text-green-500">'Authorization': 500">class="text-green-500">`Bearer ${apiKey}`,
          500">class="text-green-500">'Content-Type': 500">class="text-green-500">'application/json'
        },
        body: JSON.stringify({ message })
      });
      
      500">if (response.ok) {
        500">return response.json();
      }
      
      500">const error = 500">await response.json();
      
      500">class=500">class="text-green-500">"text-muted-foreground">// Don't retry client errors (except rate limits)
      500">if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw 500">new Error(error.message);
      }
      
      500">class=500">class="text-green-500">"text-muted-foreground">// Rate limited - wait and retry
      500">if (response.status === 429) {
        500">const retryAfter = error.details?.retry_after || 30;
        500">await sleep(retryAfter * 1000);
        continue;
      }
      
      lastError = error;
      
    } catch (err) {
      lastError = err;
    }
    
    500">class=500">class="text-green-500">"text-muted-foreground">// Exponential backoff 500">for server errors
    500">await sleep(Math.pow(2, attempt) * 1000);
  }
  
  throw lastError;
}

Handle Specific Errors

try {
  500">const result = 500">await queryAgent(agentId, message);
  displayResponse(result);
} catch (error) {
  switch (error.code) {
    case 500">class="text-green-500">'token_expired':
      500">await refreshToken();
      500">class=500">class="text-green-500">"text-muted-foreground">// Retry the request
      break;
      
    case 500">class="text-green-500">'rate_limit_exceeded':
      showMessage(500">class="text-green-500">'Please wait a moment before sending another message.');
      break;
      
    case 500">class="text-green-500">'agent_not_ready':
      showMessage(500">class="text-green-500">'The agent is still learning. Please try again in a few minutes.');
      break;
      
    case 500">class="text-green-500">'quota_exceeded':
      showMessage(500">class="text-green-500">'Monthly limit reached. Please upgrade your plan.');
      break;
      
    default:
      showMessage(500">class="text-green-500">'Something went wrong. Please try again.');
      console.error(500">class="text-green-500">'API Error:', error);
  }
}

Monitoring

Log all API errors to your monitoring system. Patterns in errors can help identify issues with your integration or our service.

Getting Help

If you encounter persistent errors:

  • Check the error message and details for specific guidance
  • Review the status page for service issues
  • Contact support with the error details and request ID (if provided)