Error Handling

How to handle errors from the FourA API, with common error codes and troubleshooting tips.

Error Response Format

All API errors return a consistent JSON structure:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded the rate limit. Try again in 30 seconds.",
    "status": 429
  }
}

Common Error Codes

400: Bad Request

The request body is missing required fields or contains invalid values.

{
  "error": {
    "code": "INVALID_PARAMS",
    "message": "Field 'url' is required and must be a valid HTTP(S) URL.",
    "status": 400
  }
}

Fix: Check that your request includes all required fields and that URLs are properly formatted.

401: Unauthorized

Your API key is missing, invalid, or expired.

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key.",
    "status": 401
  }
}

Fix: Verify your Authorization: Bearer YOUR_API_KEY header. Generate a new key from the Dashboard if needed.

429: Rate Limited

You've sent too many requests in a short period.

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 30 seconds.",
    "status": 429,
    "retryAfter": 30
  }
}

Fix: Implement exponential backoff. Check the retryAfter field for the recommended wait time.

500: Server Error

Something went wrong on our side.

Fix: Retry the request after a short delay. If the error persists, check the status page or contact support.

Best Practices

1. Always check the status code before parsing the response body.
2. Implement retries with backoff for 429 and 500 errors.
3. Log error responses for debugging: include the code and message fields.
4. Set reasonable timeouts: 30 seconds is a good default for browser tasks.

Retry Example (Python)

import requests
import time

def fetch_with_retry(url, headers, max_retries=3):
    for attempt in range(max_retries):
        resp = requests.post(url, headers=headers, json={"url": "https://example.com", "type": "single"})
        if resp.status_code == 429:
            wait = resp.json().get("error", {}).get("retryAfter", 30)
            time.sleep(wait)
            continue
        return resp
    raise Exception("Max retries exceeded")

Next Steps

• API Endpoints: Full endpoint reference
• Troubleshooting: Solutions to frequent problems
• Quick Start: Get started in 30 seconds