Frequently Asked Questions¶

Get quick answers to common questions about Helomatic's API, features, and integration.

General Questions¶

What is Helomatic?¶

Helomatic is an enterprise-grade B2B SaaS platform that provides AI-accelerated automation, monitoring, and data processing capabilities. Built on Cloudflare Workers, it offers global edge computing with enterprise security and scalability.

How does pricing work?¶

We offer tiered pricing based on usage:

Free Tier: 100 API calls/hour, basic monitoring
Pro Tier: 1,000 API calls/hour, advanced features, webhook notifications
Enterprise Tier: Custom limits, dedicated support, SLA guarantees

See our pricing page for detailed information.

What regions are supported?¶

Helomatic operates on Cloudflare's global network with 330+ edge locations across 120+ countries, ensuring low latency worldwide.

Is there an SLA?¶

Yes! We provide: - 99.9% uptime guarantee for Pro and Enterprise tiers - < 100ms response time for most API endpoints - 24/7 monitoring with automatic failover - Enterprise support with dedicated success managers

Authentication & Security¶

How does authentication work?¶

Helomatic uses JWT (JSON Web Tokens) with refresh token support:

Login with email/password to receive access + refresh tokens
Use access token for API requests (expires in 1 hour)
Refresh tokens automatically when they expire (valid for 30 days)

# Login to get tokens
curl -X POST https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"user@example.com","password":"password123"}'

# Use access token for requests
curl -H "Authorization: Bearer <access_token>" \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources

What happens when my token expires?¶

Access tokens expire after 1 hour. When you receive a 401 Unauthorized response:

Use your refresh token to get a new access token
Update your stored token with the new one
Retry the original request

Most SDKs handle this automatically.

How do I secure my API keys?¶

Best Practices: - Store tokens in environment variables, never in code - Use HTTPS only for all API communication - Rotate tokens regularly (we recommend monthly) - Monitor access patterns for unusual activity - Revoke tokens immediately if compromised

Can I restrict API access by IP?¶

Yes! Enterprise customers can configure: - IP allowlisting for enhanced security - Geographic restrictions by country/region - VPN-only access requirements - Custom authentication flows with SSO integration

Rate Limiting¶

What are the rate limits?¶

Rate limits vary by tier and endpoint:

Tier	General Endpoints	AI Endpoints	Monitoring
Free	100/hour	10/hour	20/hour
Pro	1,000/hour	100/hour	200/hour
Enterprise	10,000/hour	1,000/hour	Custom

What happens when I hit rate limits?¶

When you exceed limits, you'll receive a 429 Too Many Requests response:

{
  "success": false,
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 100,
    "remaining": 0,
    "reset_time": "2025-08-22T19:00:00.000Z",
    "retry_after": 900
  }
}

Response Headers: - X-Ratelimit-Limit: Your rate limit - X-Ratelimit-Remaining: Requests remaining - X-Ratelimit-Reset: When limit resets (Unix timestamp) - X-Ratelimit-Retry-After: Seconds to wait before retry

How can I avoid rate limits?¶

Optimization Strategies: 1. Cache responses locally when possible 2. Batch requests instead of making individual calls 3. Use webhooks instead of polling for updates 4. Implement exponential backoff for retries 5. Upgrade your tier for higher limits

Can I get higher rate limits?¶

Yes! Options include: - Upgrade to Pro/Enterprise for higher base limits - Request custom limits for specific use cases - Purchase additional capacity as needed - Use our bulk processing APIs for large datasets

API Usage¶

How do I monitor website changes?¶

Create a monitoring source with CSS or XPath selectors:

curl -X POST https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price Monitor",
    "url": "https://store.com/product/123",
    "schedule": "hourly",
    "extractors": [
      {
        "type": "css",
        "selector": ".price",
        "name": "current_price"
      }
    ],
    "webhookUrl": "https://your-app.com/webhook"
  }'

How accurate is the AI integration?¶

Our AI integration uses multiple providers (OpenAI, Grok) with: - 99.5% uptime across all AI endpoints - < 2 second average response time - Automatic failover between providers - Cost optimization routing to most efficient models

Accuracy varies by use case: - Text analysis: 95%+ accuracy - Data extraction: 90%+ accuracy
- Content generation: Highly contextual, human review recommended

Can I use custom AI models?¶

Enterprise customers can: - Bring your own models (BYOM) via API - Fine-tune models with your data - Deploy private instances for sensitive workloads - Integrate custom LLMs through our framework

What data formats are supported?¶

Input Formats: - JSON (primary) - CSV for bulk operations - XML for legacy integrations - Form data for file uploads

Output Formats: - JSON (default) - CSV for data exports - XML for specific integrations - Custom formats via transformations

How do webhooks work?¶

Webhooks provide real-time notifications:

sequenceDiagram
    participant Helomatic
    participant Your App

    Helomatic->>Your App: POST /webhook
    Note over Helomatic: Event occurs (data change, etc.)
    Your App->>Helomatic: 200 OK
    Note over Your App: Process event data

    alt Webhook fails
        Helomatic->>Your App: Retry (up to 3 times)
        Note over Helomatic: Exponential backoff
    end

Webhook Security: - HMAC-SHA256 signatures for verification - IP allowlisting available - Retry logic with exponential backoff - Delivery guarantees with persistent queues

Troubleshooting¶

"Authentication required" error¶

Problem: Receiving 401 Unauthorized responses

Solutions: 1. Check token format: Authorization: Bearer <token> 2. Verify token validity: Tokens expire after 1 hour 3. Use refresh token: Get new access token 4. Check permissions: Ensure account has required access

# Debug authentication
curl -v -H "Authorization: Bearer <token>" \
  https://helomatic-api-prod.ernijs-ansons.workers.dev/api/monitoring/sources

"Rate limit exceeded" error¶

Problem: Too many requests in time window

Solutions: 1. Implement backoff: Wait for retry_after seconds 2. Optimize requests: Use batch endpoints where available 3. Check tier limits: Upgrade if needed 4. Use caching: Store responses locally

// Example: Handle rate limits with exponential backoff
async function apiCallWithBackoff(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.status === 429) {
      const retryAfter = response.headers.get('X-Ratelimit-Retry-After');
      const delay = Math.pow(2, i) * 1000; // Exponential backoff
      await new Promise(resolve => setTimeout(resolve, delay));
      continue;
    }

    return response;
  }
  throw new Error('Max retries exceeded');
}

"Invalid input" error¶

Problem: Request validation failing

Solutions: 1. Check required fields: All required parameters included 2. Validate data types: Strings, numbers, booleans correct 3. Check field limits: Character limits, array sizes 4. Review examples: Compare with documentation

# Example: Registration with all required fields
curl -X POST https://helomatic-api-prod.ernijs-ansons.workers.dev/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "password": "SecurePass123!",
    "name": "John Doe",
    "company": "Acme Corp",
    "acceptTerms": true
  }'

Webhook not receiving data¶

Problem: Webhook endpoint not being called

Solutions: 1. Verify URL: Ensure webhook URL is publicly accessible 2. Check SSL: Webhook URLs must use HTTPS 3. Validate signature: Implement signature verification 4. Return 200 status: Always return success status 5. Check logs: Monitor for delivery attempts

// Webhook signature verification
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

Slow API responses¶

Problem: API calls taking too long

Solutions: 1. Check endpoint status: Visit /status for system health 2. Use closest region: Cloudflare automatically routes optimally 3. Optimize requests: Request only needed data 4. Enable compression: Use Accept-Encoding: gzip 5. Contact support: For persistent issues

Data not updating¶

Problem: Monitoring sources not detecting changes

Solutions: 1. Verify selectors: Test CSS/XPath selectors manually 2. Check schedule: Ensure monitoring frequency is appropriate 3. Review target site: Some sites block automated access 4. Enable retries: Configure retry attempts for failures 5. Use different extractors: Try alternative selection methods

Billing & Limits¶

How is usage calculated?¶

Usage is tracked by: - API requests: Each endpoint call counts toward limits - AI tokens: Charged based on input/output tokens - Monitoring checks: Each scheduled check counts - Data processing: Bulk operations have separate limits

Can I monitor my usage?¶

Yes! Track usage through: - Dashboard: Real-time usage metrics - API endpoint: GET /api/account/usage - Email alerts: Configurable usage warnings - Webhook notifications: Programmatic usage alerts

What happens if I exceed my plan?¶

Depending on your tier: - Free: Requests blocked until reset - Pro: Throttling with overage billing - Enterprise: Custom overage policies

Can I get refunds?¶

Our refund policy: - 30-day money-back guarantee for annual plans - Pro-rated refunds for downgrades - Enterprise: Custom terms in contract - Unused credits don't expire within plan period

Integration Support¶

Do you have SDKs?¶

Yes! Official SDKs available for: - JavaScript/TypeScript: npm install @helomatic/sdk - Python: pip install helomatic-sdk - Go: go get github.com/helomatic/sdk-go

Community SDKs for: - PHP, Ruby, Java, C#, and more

Can you help with integration?¶

Support Options: - Documentation: Comprehensive guides and examples - Email support: Technical assistance for all tiers - Live chat: Available for Pro+ customers - Dedicated success manager: Enterprise customers - Professional services: Custom integration assistance

Do you offer custom development?¶

Yes! We offer: - Custom API endpoints for specific needs - White-label solutions with your branding - On-premise deployments for enterprise security - Custom integrations with your existing systems

Platform Questions¶

What's your uptime?¶

Current uptime statistics: - 99.97% uptime over the last 12 months - < 50ms average response time globally - Zero planned downtime for maintenance - Automatic failover across multiple regions

How do you handle maintenance?¶

Our maintenance approach: - Rolling deployments with zero downtime - Blue-green architecture for seamless updates - Advance notification for any planned maintenance - Status page updates at status.helomatic.com

What about data privacy?¶

Data protection commitments: - GDPR compliant with data processing agreements - SOC 2 Type II certified security controls - Data encryption in transit and at rest - Regular security audits by third parties - Data retention policies with automated cleanup

Can I delete my data?¶

Yes! Data portability rights: - Account deletion: Complete data removal within 30 days - Data export: Download all your data in JSON format - Selective deletion: Remove specific data sets - Right to be forgotten: GDPR compliance

Still Have Questions?¶

Contact our support team: - 📧 Email: support@helomatic.com - 💬 Live Chat: Available on our website - 📞 Phone: Enterprise customers get direct phone support - 🎮 Discord: Join our community server

For technical issues: - 🐛 GitHub Issues: Report bugs and feature requests - 📚 Documentation: docs.helomatic.com - 🎯 Status Page: status.helomatic.com

This FAQ is regularly updated. Last updated: August 22, 2025