Error Handling

HTTP Status Codes

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common Errors

400 - Bad Request

Missing required fields:

{
  "success": false,
  "error": "Missing required fields: birthDate, birthTime"
}

Invalid location:

{
  "success": false,
  "error": "Could not find location: InvalidCity, InvalidCountry"
}

Invalid date format:

{
  "success": false,
  "error": "Invalid birthDate format. Use YYYY-MM-DD"
}

Invalid time format:

{
  "success": false,
  "error": "Invalid birthTime format. Use HH:MM (24-hour format)"
}

401 - Unauthorized

Missing API key:

{
  "success": false,
  "error": "API key required"
}

Invalid API key:

{
  "success": false,
  "error": "Invalid API key"
}

Revoked API key:

{
  "success": false,
  "error": "API key has been revoked"
}

402 - Payment Required

Insufficient credits:

{
  "success": false,
  "error": "Insufficient credits. Required: 500, Available: 250"
}

500 - Internal Server Error

Generation failed:

{
  "success": false,
  "error": "Failed to generate blueprint. Please try again."
}

Email delivery failed:

{
  "success": false,
  "error": "Failed to send email. Please check the email address."
}

Error Handling Best Practices

JavaScript Example

try {
  const response = await fetch('https://mycosmicadvisor.com/api/v1/generate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer bgapi_your_key_here'
    },
    body: JSON.stringify({
      birthDate: '1990-12-25',
      birthTime: '14:30',
      city: 'New York',
      country: 'USA',
      fullName: 'John Doe'
    })
  });

  const data = await response.json();

  if (!response.ok) {
    // Handle HTTP errors
    switch (response.status) {
      case 400:
        console.error('Invalid request:', data.error);
        break;
      case 401:
        console.error('Authentication failed:', data.error);
        break;
      case 402:
        console.error('Insufficient credits:', data.error);
        break;
      case 500:
        console.error('Server error:', data.error);
        break;
      default:
        console.error('Unexpected error:', data.error);
    }
    return;
  }

  // Success
  console.log('Blueprint generated:', data);
} catch (error) {
  console.error('Network error:', error);
}

Python Example

import requests

try:
    response = requests.post(
        'https://mycosmicadvisor.com/api/v1/generate',
        headers={
            'Content-Type': 'application/json',
            'Authorization': 'Bearer bgapi_your_key_here'
        },
        json={
            'birthDate': '1990-12-25',
            'birthTime': '14:30',
            'city': 'New York',
            'country': 'USA',
            'fullName': 'John Doe'
        }
    )

    data = response.json()

    if response.status_code == 200:
        print('Blueprint generated:', data)
    elif response.status_code == 400:
        print('Invalid request:', data['error'])
    elif response.status_code == 401:
        print('Authentication failed:', data['error'])
    elif response.status_code == 402:
        print('Insufficient credits:', data['error'])
    elif response.status_code == 500:
        print('Server error:', data['error'])
    else:
        print('Unexpected error:', data['error'])

except requests.exceptions.RequestException as e:
    print('Network error:', e)

Retry Logic

For transient errors (500), implement exponential backoff:

async function generateWithRetry(requestData, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch('https://mycosmicadvisor.com/api/v1/generate', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer bgapi_your_key_here'
        },
        body: JSON.stringify(requestData)
      });

      const data = await response.json();

      if (response.status === 500 && attempt < maxRetries) {
        // Wait before retrying (exponential backoff)
        const delay = Math.pow(2, attempt) * 1000;
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      return data;
    } catch (error) {
      if (attempt === maxRetries) throw error;

      const delay = Math.pow(2, attempt) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}