Error Codes Reference

Understanding error responses from the Aksita.ai API. All errors follow a consistent format with appropriate HTTP status codes.

Error Response Format

When an error occurs, the API returns a JSON response with status: false and a descriptive reason field.

{
  "status": false,
  "reason": "Descriptive error message"
}

HTTP Status Codes

200

OK

Request succeeded. Response contains requested data.

Example: Successful session creation, message sent successfully

400

Bad Request

Invalid request parameters or malformed JSON.

Reasons:

Missing required fields (session_id, message)
Invalid JSON format
Empty message content
Invalid session ID format

401

Unauthorized

Authentication failed. Invalid or missing API key.

Reasons:

Missing X-API-Key header
Invalid API key
Revoked API key
API key doesn't match agent

402

Payment Required

Insufficient credits or plan expired.

Reasons:

Insufficient credits to process request
Plan has expired
Credit balance too low

Solution: Top up credits or renew your subscription plan.

403

Forbidden

Access denied to resource.

Reasons:

Agent is disabled or deleted
Private agent access denied
Resource access not allowed

404

Not Found

Requested resource doesn't exist.

Reasons:

Session ID not found
Agent not found
Invalid endpoint URL

500

Internal Server Error

Unexpected server error. Our team is notified automatically.

Action: Retry the request after a brief delay. If the issue persists, contact support with the error timestamp.

Error Handling Best Practices

Implement Retry Logic

For 500 errors, implement exponential backoff retry strategy. Start with 1 second delay, then 2s, 4s, 8s, etc.

Validate Before Sending

Validate required fields and data formats on your end before making API calls to avoid 400 errors.

Track Remaining Credits

Every API response includes remaining_credits field. Use this to track credit balance in real-time and implement low-credit alerts.

Log Error Details

Log full error responses including timestamps for debugging. This helps when contacting support.

Example: Error Handling in JavaScript

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

    const data = await response.json();

    if (!response.ok) {
      // Handle specific error codes
      switch (response.status) {
        case 400:
          console.error('Invalid request:', data.reason);
          break;
        case 401:
          console.error('Authentication failed:', data.reason);
          break;
        case 402:
          console.error('Payment required:', data.reason);
          // Notify user to top up credits or renew plan
          alert('Insufficient credits. Please top up to continue.');
          break;
        case 403:
          console.error('Access forbidden:', data.reason);
          break;
        case 500:
          console.error('Server error:', data.reason);
          // Retry after delay
          await sleep(5000);
          return sendMessage(sessionId, message);
        default:
          console.error('Unexpected error:', data.reason);
      }
      throw new Error(data.reason);
    }

    // Success response includes remaining_credits
    // {
    //   "status": true,
    //   "data": {
    //     "response": ["AI response text"],
    //     "credits": 2,
    //     "remaining_credits": 1234,
    //     "message_id": "12345",
    //     "conversation_id": "session-id"
    //   }
    // }
    
    if (data.status && data.data) {
      const remainingCredits = data.data.remaining_credits;
      console.log('Remaining credits:', remainingCredits);
      
      // Update UI with remaining credits
      updateCreditsDisplay(remainingCredits);
      
      // Alert if credits are low
      if (remainingCredits < 100) {
        console.warn('Low credits warning!');
      }
      
      return data.data;
    }

    return data;
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
}

function sleep(ms) {
  return new Promise(resolve => setTimeout(resolve, ms));
}

function updateCreditsDisplay(credits) {
  // Update your UI with the remaining credits
  document.getElementById('credits-badge').textContent = credits;
}