Docs › Troubleshooting › Common Issues

Common Issues

Solutions to the most common problems when using the FourA API.

Empty or Incomplete Content

Symptom: The API returns a 200 status but the data field is empty or missing expected content.

Cause: The target page uses JavaScript to render content after the initial page load.

Solution: Switch from the single endpoint to the browser endpoint. Use checkText to verify the content loaded:

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/products",
    "timeout_ms": 15000,
    "checkText": "product-list"
  }'

Note: the browser endpoint returns content in the body field (not data).

403 Forbidden or Captcha Pages

Symptom: The API returns HTML containing a captcha challenge or an access denied page.

Cause: The target site detected the request as automated and blocked it.

Solution: Use the proxy endpoint for automatic IP rotation:

curl -X POST https://eu.api.foura.ai/api/proxy/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "maxTries": 5,
    "request": {
      "method": "GET",
      "url": "https://example.com/prices",
      "unblocker": true
    }
  }'

If the issue persists, increase maxTries to give the proxy rotation more attempts.

Timeout Errors

Symptom: Requests fail with a timeout error.

Cause: The target page takes longer to load than the configured timeout.

Solution: Increase timeout_ms (default is 15s for single, 30s for browser, 45s for proxy):

curl -X POST https://eu.api.foura.ai/api/browser/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://slow-site.com",
    "timeout_ms": 60000
  }'

For browser requests, also verify your checkText value actually appears on the page. A typo will always cause a timeout.

429 Too Many Requests (RPM Limit)

Symptom: API returns 429 status with a "rate limit exceeded" message.

Cause: You've exceeded your requests-per-minute (RPM) limit. This is different from concurrency limits (see 503 below).

Solution: Use the retryAfter field from the response to wait the right amount of time before retrying:

import time
import requests

def make_request(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code == 429:
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Rate limit not resolved after retries")

# Example: single request
make_request(
    "https://eu.api.foura.ai/api/single/",
    {"method": "GET", "url": "https://example.com"}
)

Check your current usage in the Dashboard to see your rate limits.

503 Service Unavailable

Symptom: API returns 503 status.

Cause: This happens in two cases:

  1. Concurrency limit hit. You have too many simultaneous requests running. This is different from 429, which limits requests per minute. With 503, you haven't exceeded your RPM, but you've maxed out the number of requests that can run at the same time.
  2. Service temporarily disabled. A maintenance window is in progress.

Both cases include a retryAfter field in the response.

Solution: Wait for retryAfter seconds, then retry:

import time
import requests

def make_request_with_retry(endpoint_url, payload, retries=3):
    for i in range(retries):
        resp = requests.post(
            endpoint_url,
            headers={"X-API-Key": "YOUR_API_KEY", "Content-Type": "application/json"},
            json=payload
        )
        if resp.status_code in (429, 503):
            body = resp.json()
            wait = body.get("retryAfter", 2 ** i)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Request not resolved after retries")

If you're hitting 503 concurrency limits regularly, reduce the number of parallel requests in your scraping pipeline, or check your plan's concurrency limit in the Dashboard.

401 Authentication Errors

Symptom: Every request returns 401 Unauthorized.

Checklist:

  1. Verify the header is X-API-Key: YOUR_API_KEY (not Authorization: Bearer or Api-Key)
  2. Check for extra whitespace or newlines in your API key
  3. Create a fresh key from the Dashboard if the current one might be compromised

Unexpected HTML Instead of JSON

Symptom: You expected JSON from the target site but received HTML.

Cause: The target page may serve different content based on headers.

Solution: Add an Accept header and enable unblocker for realistic browser headers:

curl -X POST https://eu.api.foura.ai/api/single/ \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "method": "GET",
    "url": "https://api.example.com/data",
    "headers": [["Accept", "application/json"]],
    "unblocker": true
  }'

You can also set tryJsonData to true to have FourA automatically parse JSON responses.

Still Stuck?

If none of the above solutions work:

  1. Check the status page for any ongoing incidents
  2. Review your request metrics in the Dashboard
  3. Contact support at support@foura.ai with your request details

Next Steps

Last updated: April 27, 2026