Error Codes & Troubleshooting

WebPerception API uses standard HTTP status codes. This guide covers every error you might encounter and how to fix it.

HTTP Status Codes

Common Issues

401 — "Invalid API Key"

Your API key is missing, malformed, or revoked.

Fix:

• Check that you're sending the key in the Authorization: Bearer YOUR_API_KEY header
• Verify the key in your dashboard
• Make sure there are no extra spaces or newlines in the key
• If using environment variables, confirm they're loaded: echo $MANTIS_API_KEY

# ✅ Correct
curl -X POST https://api.mantisapi.com/v1/scrape \
  -H "Authorization: Bearer sk_live_abc123..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com"}'

# ❌ Wrong — missing "Bearer" prefix
curl -X POST https://api.mantisapi.com/v1/scrape \
  -H "Authorization: sk_live_abc123..."

429 — Rate Limited

You've exceeded your plan's requests-per-second limit.

Implement exponential backoff:

import time
import requests

def scrape_with_retry(url, api_key, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.mantisapi.com/v1/scrape",
            headers={"Authorization": f"Bearer {api_key}"},
            json={"url": url}
        )
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 2 ** attempt))
            print(f"Rate limited. Waiting {wait}s...")
            time.sleep(wait)
            continue
        return response
    raise Exception("Max retries exceeded")

422 — Page Can't Be Processed

The target page loaded but couldn't be scraped. Common causes:

• CAPTCHA: The site is showing a CAPTCHA challenge. Try enabling "render_js": true and "proxy_country": "US"
• Login wall: The page requires authentication. WebPerception can't bypass login pages.
• Empty page: JavaScript-heavy SPA that needs more time. Use "wait_for": "selector" with a CSS selector.

502 — Target Site Timeout

The website you're scraping took too long to respond (>30 seconds).

Fix:

• Check if the target site is actually online
• Try without "render_js": true — JS rendering adds time
• Some sites are slow during peak hours — retry later

Empty or Unexpected Content

You got a 200 response but the content isn't what you expected.

# Many modern sites need JS rendering
response = requests.post(
    "https://api.mantisapi.com/v1/scrape",
    headers={"Authorization": f"Bearer {api_key}"},
    json={
        "url": "https://example.com/dynamic-page",
        "render_js": True,
        "wait_for": ".product-card"  # Wait for this element
    }
)

AI Extraction Errors

Extraction Returns Empty or Wrong Data

• Schema too complex: Simplify your extraction schema. Start with 2-3 fields, then add more.
• Ambiguous field names: Use descriptive names. "product_price_usd" works better than "price".
• Wrong page content: Make sure the URL actually contains the data you're extracting. Use /scrape first to verify.

Credit Usage

Failed requests are not charged. If a request returns a 4xx or 5xx error, no credits are deducted from your account.

Still Stuck?