Skip to main content

​
Common Issues

​
Authentication Errors

Cause: Missing or incorrect Authorization headerSolution:
# Correct format
curl -H "Authorization: Bearer YOUR_API_KEY" ...

# NOT these:
# Authorization: YOUR_API_KEY
# Bearer YOUR_API_KEY
Verify your API key is correct and not expired.
Cause: API key is invalid, revoked, or expiredSolution:
  1. Log in to https://app.aimon.ai
  2. Go to Account → API Key
  3. Generate a new API key
  4. Update your application with the new key
Cause: Exceeded rate limits (100 requests/minute)Solution:
  • Implement exponential backoff
  • Add delays between requests
  • Cache responses when possible
  • Contact support for higher limits
import time
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

retry_strategy = Retry(
    total=3,
    status_forcelist=[429, 500, 502, 503, 504],
    backoff_factor=2
)

​
Dataset Issues

Possible causes:
  • File too large (>100 MB)
  • File corrupted
  • Incorrect encoding (not UTF-8)
  • Unsupported file format
Solutions:
  • Check file size: ls -lh yourfile.csv
  • Verify file opens correctly
  • Convert to UTF-8: iconv -f ISO-8859-1 -t UTF-8 input.csv > output.csv
  • Ensure correct file extension
Cause: Incorrect folder structure in ZIPSolution:
  • Folders must be at ZIP root, not nested
  • No empty folders
  • No files at root level
# Correct way to create ZIP
cd your_data_folder
zip -r ../data.zip .

# Verify structure
unzip -l ../data.zip
Problem: Created SINGLE_FILE but need MULTI_FILESolution:
  • Dataset type cannot be changed after creation
  • Delete the dataset
  • Create new dataset with correct type
  • Re-upload files

​
Analysis & Specification Issues

Normal duration: 2-10 minutesIf longer than 15 minutes:
  • Check status endpoint for errors
  • Verify dataset files are not corrupt
  • Try with smaller dataset first
  • Contact support if persistent
Common causes:
  • Dataset files corrupted or unreadable
  • Unsupported file format
  • Files not UTF-8 encoded
  • Dataset too small (<3 samples)
Solution:
  • Check error message in status response
  • Verify all files are valid
  • Ensure at least 3-5 samples in dataset
  • Test with known-good data first
Problem: Specification misses important patternsSolution:
  • Manually edit the specification
  • Add specific requirements explicitly
  • Provide more diverse seed data
  • Add examples of edge cases
Problem: Invalid YAML when updating specificationSolution:
  • Validate YAML: https://www.yamllint.com/
  • Use spaces for indentation, not tabs
  • Escape special characters
  • Use | for multiline strings:
requirements: |
  - First requirement
  - Second requirement
  - Third requirement

​
Generation Issues

Normal times:
  • Short samples: 5-30 seconds each
  • Long samples: 2-10 minutes each
If much slower:
  • Check status for progress updates
  • High system load may slow processing
  • Large batches take longer
  • Contact support if no progress for 30+ minutes
Common causes:
  • Specification not in READY status
  • Wrong sample type for dataset
  • Invalid parameters
  • Model timeout
Solution:
  • Verify spec status is READY
  • Use long samples for structured data (CSV, JSON)
  • Check error message in status response
  • Try with smaller batch (5-10 samples)
Cause: Short samples incompatible with dataset typeSolution:
  • Use sample_type: "long" instead
  • Short samples don’t work for:
    • Single-file CSV/JSON/JSONL datasets
    • Complex structured data
Problem: Samples don’t match requirementsSolutions:
  1. Review and clarify specification requirements
  2. Add more specific constraints
  3. Provide better quality seed data
  4. Try different model (e.g., claude-sonnet vs haiku)
  5. Adjust temperature (0.5-0.8 for balance)
Problem: Generated samples lack diversitySolutions:
  • Increase temperature (try 0.8-0.9)
  • Add more variation axes to specification
  • Ensure variation values are distinct
  • Generate larger batch for better distribution
  • Provide more diverse seed data

​
Evaluation Issues

Cause: Samples don’t meet requirementsSolutions:
  • Review failed samples to identify patterns
  • Clarify vague requirements in spec
  • Simplify complex or contradictory requirements
  • Add format examples to specification
  • Try different model
Cause: Some variation values rarely appearSolutions:
  • Clarify variation axis descriptions
  • Make all variation values equally specific
  • Reduce number of variation axes
  • Generate larger batch
  • Regenerate with adjusted spec
Normal time: 5-10 minutes for 100 samplesIf longer:
  • Wait up to 15 minutes
  • Check evaluation status periodically
  • Large batches take proportionally longer
  • Contact support if stuck >30 minutes

​
Local Development Issues

Causes:
  • Docker not running
  • Port conflicts
  • Insufficient resources
Solutions:
# Check Docker is running
docker info

# Check for port conflicts
lsof -i :3001
lsof -i :8000

# View container logs
docker compose logs service-name

# Rebuild containers
docker compose build --no-cache
docker compose up
Problem: SQS/S3 services unavailableSolutions:
# Restart LocalStack
docker compose restart localstack

# Check LocalStack health
curl http://localhost:4566/_localstack/health

# Verify queues exist
aws --endpoint-url=http://localhost:4566 sqs list-queues

# Recreate queues if needed
cd dataframer-in-box
docker exec sqs-setup /bin/sh /sqs-setup.sh
Problem: Django migrations failSolutions:
# Access backend container
docker compose exec ui-backend bash

# Run migrations manually
python manage.py makemigrations
python manage.py migrate

# If persistent, clean volumes
./dataframer_manager.sh
# Select: "Clean data volumes and restart"
Cause: Network or configuration issuesSolutions:
  • Verify all services are running: docker compose ps
  • Check service logs: docker compose logs postgres redis
  • Verify /etc/hosts configuration
  • Restart affected services: docker compose restart service-name

​
Error Messages Reference

​
Common Error Codes

ErrorStatusMeaningSolution
Authentication failed401Invalid API keyCheck API key format and validity
Permission denied403Insufficient permissionsVerify API key has access
Resource not found404Dataset/spec doesn’t existCheck resource ID is correct
Invalid parameters400Bad request dataReview API documentation
Rate limit exceeded429Too many requestsImplement backoff/retry logic
Server error500Internal errorRetry or contact support
Timeout504Request took too longReduce batch size or retry

​
Getting Help

​
Before Contacting Support

Gather this information:
  1. Error message (complete error text)
  2. Request details (endpoint, parameters)
  3. Resource IDs (dataset_id, spec_id, task_id)
  4. Timestamp of when error occurred
  5. Steps to reproduce the issue

​
Debugging Tips

Enable verbose logging: 
import logging
logging.basicConfig(level=logging.DEBUG)
Check API response: 
response = requests.post(url, headers=headers, json=data)
print(f"Status: {response.status_code}")
print(f"Response: {response.text}")
Verify environment: 
# Check API connectivity
curl -I https://df-api.dataframer.ai/health

# Test authentication
curl -H "Authorization: Bearer $API_KEY" \
  https://df-api.dataframer.ai/api/users/me/

​
FAQ

  • Short samples: 5-30 seconds each
  • Long samples: 2-10 minutes each
  • Total time depends on batch size and available workers
  • Large batches (100+) may take several hours
  • Maximum file size: 100 MB per file
  • Maximum samples: 1000 per dataset
  • Recommended: 10-50 samples for best results
  • Minimum: 3-5 samples for meaningful analysis
Currently, generation cannot be canceled once started. The task will run to completion or failure.
  1. Clarify specification requirements
  2. Provide higher quality seed data
  3. Use appropriate sample type (short vs long)
  4. Adjust temperature (0.7 is default)
  5. Try different models
  6. Iterate: generate small batches, review, refine
  • anthropic/claude-sonnet-4-5 (default, recommended)
  • anthropic/claude-haiku-4-5 (faster, lower cost)
  • gemini/gemini-2.5-pro (complex reasoning)
  • openai/gpt-4.1 (alternative high quality)

​
Still Need Help?