Error Handling

Complete reference for error codes, messages, and troubleshooting in the Boring API.

Error Response Format

All errors return JSON with the following structure:

{
  "success": false,
  "error": "ErrorCode",
  "message": "Human-readable error description"
}

HTTP status codes indicate the error category:

Authentication Errors

InvalidApiKey

HTTP Status: 401

{
  "success": false,
  "error": "InvalidApiKey",
  "message": "Invalid or missing API key"
}

Causes:

Solutions:

Unauthorized

HTTP Status: 401

{
  "success": false,
  "error": "Unauthorized",
  "message": "Authentication required"
}

Causes:

Solutions:

Account Errors

InvalidAccountId

HTTP Status: 400

{
  "success": false,
  "error": "InvalidAccountId",
  "message": "Account not found or does not belong to this user"
}

Causes:

Solutions:

AccountDisabled

HTTP Status: 400

{
  "success": false,
  "error": "AccountDisabled",
  "message": "This account has been disconnected"
}

Causes:

Solutions:

TokenExpired

HTTP Status: 401

{
  "success": false,
  "error": "TokenExpired",
  "message": "Access token has expired"
}

Causes:

Solutions:

InvalidToken

HTTP Status: 401

{
  "success": false,
  "error": "InvalidToken",
  "message": "Access token is invalid or revoked"
}

Causes:

Solutions:

Request Errors

InvalidRequest

HTTP Status: 400

{
  "success": false,
  "error": "InvalidRequest",
  "message": "Invalid request format"
}

Causes:

Solutions:

MissingParameter

HTTP Status: 400

{
  "success": false,
  "error": "MissingParameter",
  "message": "Required parameter missing: accountId"
}

Causes:

Solutions:

InvalidPlatform

HTTP Status: 400

{
  "success": false,
  "error": "InvalidPlatform",
  "message": "Platform must be 'facebook', 'instagram', or 'threads'"
}

Causes:

Solutions:

Media Errors

MediaDownloadFailed

HTTP Status: 400

{
  "success": false,
  "error": "MediaDownloadFailed",
  "message": "Failed to download media from URL: https://..."
}

Causes:

Solutions:

InvalidMediaType

HTTP Status: 400

{
  "success": false,
  "error": "InvalidMediaType",
  "message": "Unsupported media type: application/pdf"
}

Causes:

Solutions:

InvalidMediaUrl

HTTP Status: 400

{
  "success": false,
  "error": "InvalidMediaUrl",
  "message": "Invalid media URL format"
}

Causes:

Solutions:

MediaTooLarge

HTTP Status: 400

{
  "success": false,
  "error": "MediaTooLarge",
  "message": "Media file exceeds maximum size: 100MB"
}

Causes:

Solutions:

Content Errors

TextRequired

HTTP Status: 400

{
  "success": false,
  "error": "TextRequired",
  "message": "Text is required for this post type"
}

Causes:

Solutions:

MediaRequired

HTTP Status: 400

{
  "success": false,
  "error": "MediaRequired",
  "message": "Instagram requires at least one media item"
}

Causes:

Solutions:

InvalidCarouselSize

HTTP Status: 400

{
  "success": false,
  "error": "InvalidCarouselSize",
  "message": "Carousel must have 2-10 images for Instagram"
}

Causes:

Solutions:

TextTooLong

HTTP Status: 400

{
  "success": false,
  "error": "TextTooLong",
  "message": "Text exceeds maximum length: 500 characters for Threads"
}

Causes:

Solutions:

InvalidTextFormat

HTTP Status: 400

{
  "success": false,
  "error": "InvalidTextFormat",
  "message": "Text must be string or array of strings"
}

Causes:

Solutions:

Publishing Errors

PublishingFailed

HTTP Status: 500

{
  "success": false,
  "error": "PublishingFailed",
  "message": "Failed to publish post",
  "details": "Platform error message"
}

Causes:

Solutions:

VideoProcessingFailed

HTTP Status: 500

{
  "success": false,
  "error": "VideoProcessingFailed",
  "message": "Video processing timed out or failed"
}

Causes:

Solutions:

CarouselCreationFailed

HTTP Status: 500

{
  "success": false,
  "error": "CarouselCreationFailed",
  "message": "Failed to create carousel container"
}

Causes:

Solutions:

Rate Limiting

RateLimitExceeded

HTTP Status: 429

{
  "success": false,
  "error": "RateLimitExceeded",
  "message": "Rate limit exceeded. Try again in 3600 seconds",
  "retry_after": 3600
}

Causes:

Solutions:

Platform limits:

Permission Errors

InsufficientPermissions

HTTP Status: 403

{
  "success": false,
  "error": "InsufficientPermissions",
  "message": "Missing required permission: threads_manage_replies"
}

Causes:

Solutions:

Server Errors

InternalServerError

HTTP Status: 500

{
  "success": false,
  "error": "InternalServerError",
  "message": "An unexpected error occurred"
}

Causes:

Solutions:

ServiceUnavailable

HTTP Status: 503

{
  "success": false,
  "error": "ServiceUnavailable",
  "message": "Service temporarily unavailable"
}

Causes:

Solutions:

Timeout

HTTP Status: 504

{
  "success": false,
  "error": "Timeout",
  "message": "Request timed out"
}

Causes:

Solutions:

Error Handling Best Practices

1. Always Check Success Flag

response = requests.post(API_URL, headers=headers, json=data)
result = response.json()

if not result.get("success"):
    handle_error(result["error"], result["message"])
    return None

return result["data"]

2. Implement Retry Logic

RETRYABLE_ERRORS = [
    "RateLimitExceeded",
    "ServiceUnavailable",
    "Timeout",
    "InternalServerError"
]

def should_retry(error_code):
    return error_code in RETRYABLE_ERRORS

def publish_with_retry(data, max_attempts=3):
    for attempt in range(max_attempts):
        try:
            result = publish(data)

            if result["success"]:
                return result

            if not should_retry(result.get("error")):
                return result  # Don't retry

            wait_time = result.get("retry_after", 2 ** attempt)
            time.sleep(wait_time)

        except Exception as e:
            if attempt == max_attempts - 1:
                raise

    return {"success": False, "error": "MaxRetriesExceeded"}

3. Log All Errors

import logging

logger = logging.getLogger(__name__)

def handle_api_error(error_code, message, context=None):
    logger.error(f"API Error: {error_code} - {message}")

    if context:
        logger.error(f"Context: {context}")

    # Send alert for critical errors
    if error_code in ["TokenExpired", "InsufficientPermissions"]:
        send_admin_alert(error_code, message)

4. User-Friendly Messages

ERROR_MESSAGES = {
    "InvalidApiKey": "Your API key is invalid. Please check your Settings.",
    "TokenExpired": "Your account connection has expired. Please reconnect your account.",
    "MediaDownloadFailed": "We couldn't access your media. Please check the URL.",
    "RateLimitExceeded": "You're publishing too fast. Please wait a few minutes."
}

def get_user_message(error_code):
    return ERROR_MESSAGES.get(error_code, "An error occurred. Please try again.")

5. Monitor Error Rates

from collections import Counter

error_counter = Counter()

def track_error(error_code):
    error_counter[error_code] += 1

    # Alert if error rate is high
    if error_counter[error_code] > 10:
        notify_admin(f"High error rate for {error_code}")

Debugging

Enable Verbose Logging

import logging

logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

Inspect Full Response

response = requests.post(API_URL, headers=headers, json=data)

print("Status Code:", response.status_code)
print("Headers:", response.headers)
print("Body:", response.text)

Test Media URLs

# Test if media is accessible
curl -I https://example.com/image.jpg

# Should return:
# HTTP/2 200
# content-type: image/jpeg
# content-length: 123456

Validate JSON

import json

try:
    data = json.loads(request_body)
except json.JSONDecodeError as e:
    print(f"Invalid JSON: {e}")

Getting Help

If you're stuck:

  1. Check this error reference - Find your error code
  2. Review platform guides - See platform-specific requirements
  3. Check examples - Compare with working code
  4. Test in isolation - Try simplest possible request
  5. Check status pages - Verify platforms are operational
  6. Contact support - Provide error details and context

Next Steps