Skip to main content
All API errors follow a consistent format to help you handle them gracefully.

​
Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message"
  },
  "metadata": {
    "credits_used": 0,
    "processing_time": 0.012
  }
}

​
Error Codes Reference

​
Authentication Errors

CodeHTTP StatusDescription
UNAUTHORIZED401Missing or invalid API key
PAYMENT_REQUIRED402Insufficient credits

​
Request Errors

CodeHTTP StatusDescription
BAD_REQUEST400Invalid request parameters
NOT_FOUND404Resource not found
RATE_LIMITED429Too many requests

​
Server Errors

CodeHTTP StatusDescription
SERVICE_UNAVAILABLE503Temporary service outage (circuit breaker)
EXTERNAL_API_ERROR502External platform API error
INTERNAL_SERVER_ERROR500Unexpected server error

​
Handling Common Errors

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}
Solution: Check that your API key is correct and hasn’t expired.
{
  "success": false,
  "error": {
    "code": "BAD_REQUEST",
    "message": "limit exceeds max"
  }
}
Solution: Reduce the limit parameter. Maximum varies by endpoint (typically 100 for posts, 500 for comments).
{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable"
  }
}
Solution: The circuit breaker is open due to upstream issues. Retry after a few seconds with exponential backoff.
{
  "success": false,
  "error": {
    "code": "EXTERNAL_API_ERROR",
    "message": "External API returned 404: Post not found"
  }
}
Solution: The external platform returned an error. Check that the resource exists and the URL/ID is correct.

​
Error Handling Examples

import requests
from time import sleep

def fetch_with_retry(url, payload, max_retries=3):
    headers = {
        "X-API-Key": "your-api-key",
        "Content-Type": "application/json"
    }

    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=payload)
        data = response.json()

        if data["success"]:
            return data

        error_code = data["error"]["code"]

        # Don't retry client errors
        if error_code in ["UNAUTHORIZED", "BAD_REQUEST", "NOT_FOUND"]:
            raise Exception(f"Client error: {data['error']['message']}")

        # Retry server errors with backoff
        if error_code in ["SERVICE_UNAVAILABLE", "RATE_LIMITED"]:
            wait_time = 2 ** attempt  # 1, 2, 4 seconds
            print(f"Retrying in {wait_time}s...")
            sleep(wait_time)
            continue

        raise Exception(f"API error: {data['error']['message']}")

    raise Exception("Max retries exceeded")

​
Best Practices

Always check success

Don’t assume the request succeeded

Log error codes

Track which errors occur most frequently

Implement retry logic

For transient errors like SERVICE_UNAVAILABLE

Use exponential backoff

Start with 1s, then 2s, 4s, etc.