Skip to main content

​
Error Response Format

All errors follow a consistent structure: 
{
  "success": false,
  "data": null,
  "error": "Error message description"
}

​
HTTP Status Codes

CodeNameDescription
200OKRequest succeeded
201CreatedResource created successfully
400Bad RequestInvalid request parameters
401UnauthorizedMissing or invalid API key
403ForbiddenInsufficient permissions
404Not FoundResource doesn’t exist
429Too Many RequestsRate limit exceeded
500Internal Server ErrorSomething went wrong on our end

​
Common Errors

​
Authentication Errors

HTTP 401
{
  "success": false,
  "data": null,
  "error": "Missing API key"
}
Solution: Include x-api-key header in your request
HTTP 401
{
  "success": false,
  "data": null,
  "error": "Invalid or inactive API key"
}
Solutions:
  • Verify your API key is correct
  • Check if the key has been revoked
  • Generate a new key from the dashboard
HTTP 403
{
  "success": false,
  "data": null,
  "error": "Insufficient permissions"
}
Solutions:
  • Upgrade from read to write scope
  • Request company-wide access
  • Use a different API key

​
Validation Errors

HTTP 400
{
  "success": false,
  "data": null,
  "error": "campaignId is required"
}
Solution: Include all required fields in your request
HTTP 403
{
  "success": false,
  "data": null,
  "error": "Campaign not found or access denied"
}
Solutions:
  • Verify the campaignId is correct
  • Check your API key has access to this campaign
  • Ensure the campaign belongs to your company
HTTP 400
{
  "success": false,
  "data": null,
  "error": "Lead with this phone number already exists"
}
Solution: Use a different phone number or update the existing lead

​
Rate Limit Errors

HTTP 429
{
  "success": false,
  "data": null,
  "error": "Rate limit exceeded"
}
Response Headers:
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1640000000
Solutions:
  • Wait until the reset time
  • Implement exponential backoff
  • Contact us for higher limits

​
Error Handling Best Practices

​
1. Check Status Codes

JavaScript
const response = await fetch('https://lupitor.acrely.ai/api/v1/leads', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(leadData)
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${response.status}:`, error.error);
  // Handle specific status codes
  if (response.status === 401) {
    // Invalid API key
  } else if (response.status === 429) {
    // Rate limited
  }
}

const data = await response.json();

​
2. Implement Retry Logic

Python
import time
import requests

def create_lead_with_retry(lead_data, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.post(
                'https://lupitor.acrely.ai/api/v1/leads',
                headers={'x-api-key': 'YOUR_API_KEY'},
                json=lead_data,
                timeout=30
            )

            if response.status_code == 429:
                # Rate limited - wait and retry
                wait_time = 2 ** attempt  # Exponential backoff
                time.sleep(wait_time)
                continue

            response.raise_for_status()
            return response.json()

        except requests.exceptions.RequestException as e:
            if attempt == max_retries - 1:
                raise
            time.sleep(2 ** attempt)

    raise Exception("Max retries exceeded")

​
3. Log Errors Properly

JavaScript
async function createLead(leadData) {
  try {
    const response = await fetch('https://lupitor.acrely.ai/api/v1/leads', {
      method: 'POST',
      headers: {
        'x-api-key': process.env.API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(leadData)
    });

    const data = await response.json();

    if (!data.success) {
      console.error('API Error:', {
        status: response.status,
        error: data.error,
        leadData: leadData,
        timestamp: new Date().toISOString()
      });
      throw new Error(data.error);
    }

    return data.data;

  } catch (error) {
    console.error('Request failed:', error);
    throw error;
  }
}

​
4. Handle Rate Limits Gracefully

Python
import time
from datetime import datetime

def handle_rate_limit(response):
    """Wait until rate limit resets"""
    if response.status_code == 429:
        reset_time = int(response.headers.get('X-RateLimit-Reset', 0))
        if reset_time:
            wait_seconds = reset_time - int(time.time())
            if wait_seconds > 0:
                print(f"Rate limited. Waiting {wait_seconds} seconds...")
                time.sleep(wait_seconds + 1)
                return True
    return False

​
Getting Help

If you encounter errors you can’t resolve:
  1. Check this documentation for common solutions
  2. Review API logs in your dashboard
  3. Contact support at info@acrely.ai
  4. Text the Creator! That’s right, my personal number! +l 4l2 5OO lOOl
When reporting errors, include:
  • The HTTP status code
  • The error message
  • Your request (without sensitive data)
  • Timestamp of the error