Error Handling

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

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Missing or invalid API key
`PAYMENT_REQUIRED`	402	Insufficient credits

Request Errors

Code	HTTP Status	Description
`BAD_REQUEST`	400	Invalid request parameters
`NOT_FOUND`	404	Resource not found
`RATE_LIMITED`	429	Too many requests

Server Errors

Code	HTTP Status	Description
`SERVICE_UNAVAILABLE`	503	Temporary service outage (circuit breaker)
`EXTERNAL_API_ERROR`	502	External platform API error
`INTERNAL_SERVER_ERROR`	500	Unexpected server error

Handling Common Errors

Invalid API Key

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

Solution: Check that your API key is correct and hasn’t expired.

Limit Exceeds Maximum

{
  "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).

Service Temporarily Unavailable

{
  "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.

External API Error

{
  "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")

async function fetchWithRetry(url, payload, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, {
      method: "POST",
      headers: {
        "X-API-Key": "your-api-key",
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    const data = await response.json();

    if (data.success) {
      return data;
    }

    const errorCode = data.error.code;

    // Don't retry client errors
    if (["UNAUTHORIZED", "BAD_REQUEST", "NOT_FOUND"].includes(errorCode)) {
      throw new Error(`Client error: ${data.error.message}`);
    }

    // Retry server errors with backoff
    if (["SERVICE_UNAVAILABLE", "RATE_LIMITED"].includes(errorCode)) {
      const waitTime = Math.pow(2, attempt) * 1000;
      console.log(`Retrying in ${waitTime/1000}s...`);
      await new Promise(r => setTimeout(r, waitTime));
      continue;
    }

    throw new Error(`API error: ${data.error.message}`);
  }

  throw new Error("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.

Introduction

Getting Started

Core Concepts

Platform Guides

Coming Soon

Error Response Format

Error Codes Reference

Authentication Errors

Request Errors

Server Errors

Handling Common Errors

Error Handling Examples

Best Practices

Always check success

Log error codes

Implement retry logic

Use exponential backoff

​Error Response Format

​Error Codes Reference

​Authentication Errors

​Request Errors

​Server Errors

​Handling Common Errors

​Error Handling Examples

​Best Practices

Always check success

Log error codes

Implement retry logic

Use exponential backoff

Error Response Format

Error Codes Reference

Authentication Errors

Request Errors

Server Errors

Handling Common Errors

Error Handling Examples

Best Practices