Error Handling

Error Response Format

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "invalid_request",
    "message": "The url field is required",
    "field": "url"
  }
}

Fields:

code - Machine-readable error code (e.g., invalid_request, rate_limit_exceeded)
message - Human-readable error description
field - (Optional) The specific field that caused the error

HTTP Status Codes

Status Code	Description
`200 OK`	Request successful
`201 Created`	Resource created successfully
`400 Bad Request`	Invalid request parameters
`401 Unauthorized`	Missing or invalid API key
`403 Forbidden`	Insufficient permissions or quota exceeded
`404 Not Found`	Resource not found
`409 Conflict`	Resource conflict (e.g., slug already exists)
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Server error (contact support if persists)

Common Errors

401 Unauthorized - Missing API Key

{
  "error": {
    "code": "missing_api_key",
    "message": "API key is required. Include it in the Authorization header as a Bearer token."
  }
}

Solution: Add your API key to the Authorization header as a Bearer token (e.g., Authorization: Bearer bcy_live_pk_YOUR_API_KEY).

401 Unauthorized - Invalid API Key

{
  "error": {
    "code": "invalid_api_key",
    "message": "API key is invalid or has been revoked"
  }
}

Solutions:

Verify you’ve copied the full API key correctly
Check if the key has been revoked in the API Dashboard
Generate a new API key if needed

403 Forbidden - Plan Upgrade Required

{
  "error": {
    "code": "plan_upgrade_required",
    "message": "Your subscription plan does not include API access. Please upgrade to Growth or higher.",
    "currentPlan": "solo"
  }
}

Solution: Upgrade to a Growth plan ($35/month) or higher.

403 Forbidden - Quota Exceeded

{
  "error": {
    "code": "quota_exceeded",
    "message": "You've reached your plan's link limit",
    "currentPlan": "growth",
    "currentLinks": 1000,
    "maxLinks": 1000
  }
}

Solutions:

Delete unused links
Upgrade your plan for higher limits

404 Not Found

{
  "error": {
    "code": "link_not_found",
    "message": "Link not found"
  }
}

Solutions:

Check that the link ID is correct
Verify the link hasn’t been deleted
Ensure you have permission to access this link

409 Conflict - Slug Already Exists

{
  "error": {
    "code": "slug_already_exists",
    "message": "The slug 'summer' is already in use"
  }
}

Solutions:

Choose a different slug
Omit the slug field to auto-generate a random one
Check if you already created this link

429 Too Many Requests - Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded",
    "limit": 1000,
    "remaining": 0,
    "resetAt": 1738886400
  }
}

Solution: Wait until the rate limit resets (see resetAt timestamp) or upgrade your plan.

Rate Limiting

Rate Limit Headers

Every API response includes rate limit information in the headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1738886400

X-RateLimit-Limit - Your maximum requests per hour
X-RateLimit-Remaining - Requests remaining in current window
X-RateLimit-Reset - Unix timestamp when limit resets

Rate Limits by Plan

Plan	Requests/Hour	Requests/Day
Growth	1,000	10,000
Scaling	5,000	50,000
Dominance	10,000	100,000

Handling Rate Limits

async function makeRequest(url, options) {
  const response = await fetch(url, options);

  // Check if rate limited
  if (response.status === 429) {
    const resetTime = response.headers.get('X-RateLimit-Reset');
    const waitMs = (resetTime * 1000) - Date.now();

    console.log(`Rate limited. Waiting ${waitMs}ms...`);
    await new Promise(resolve => setTimeout(resolve, waitMs));

    // Retry request
    return makeRequest(url, options);
  }

  return response.json();
}

import time
import requests

def make_request(url, headers):
    response = requests.get(url, headers=headers)

    # Check if rate limited
    if response.status_code == 429:
        reset_time = int(response.headers.get('X-RateLimit-Reset'))
        wait_seconds = reset_time - int(time.time())

        print(f"Rate limited. Waiting {wait_seconds}s...")
        time.sleep(wait_seconds)

        # Retry request
        return make_request(url, headers)

    return response.json()

Best Practices for Rate Limiting

Monitor rate limit headers

Check X-RateLimit-Remaining before making requests:

const remaining = response.headers.get('X-RateLimit-Remaining');
if (remaining < 10) {
  console.warn('Approaching rate limit!');
}

Implement exponential backoff

Retry failed requests with increasing delays:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
}

Batch requests when possible

Use bulk endpoints to reduce request count:

Use POST /v1/links/bulk instead of multiple single creates
Use DELETE /v1/links/bulk for deleting multiple links

Cache responses

Cache data that doesn’t change frequently:

const cache = new Map();

async function getCachedLink(linkId) {
  if (cache.has(linkId)) {
    return cache.get(linkId);
  }

  const link = await fetchLink(linkId);
  cache.set(linkId, link);
  return link;
}

Retry Logic

Implement automatic retries for transient errors (500, 502, 503, 504):

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      // Don't retry client errors (4xx)
      if (response.status >= 400 && response.status < 500) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Retry server errors (5xx)
      if (response.status >= 500 && attempt < maxRetries) {
        const delay = Math.pow(2, attempt) * 1000;
        console.log(`Retry ${attempt}/${maxRetries} after ${delay}ms`);
        await new Promise(resolve => setTimeout(resolve, delay));
        continue;
      }

      return response.json();
    } catch (error) {
      if (attempt === maxRetries) throw error;
    }
  }
}

import time
import requests
from requests.adapters import HTTPAdapter
from requests.packages.urllib3.util.retry import Retry

def create_session_with_retries():
    session = requests.Session()

    retry_strategy = Retry(
        total=3,
        status_forcelist=[429, 500, 502, 503, 504],
        backoff_factor=2  # 2s, 4s, 8s
    )

    adapter = HTTPAdapter(max_retries=retry_strategy)
    session.mount("https://", adapter)

    return session

# Usage
session = create_session_with_retries()
response = session.get(
    'https://api.bouncy.ai/v1/links',
    headers={'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY'}
)

Validation Errors

Field-specific validation errors include the field property:

{
  "error": {
    "code": "invalid_url",
    "message": "The URL must be a valid HTTP or HTTPS URL",
    "field": "url"
  }
}

Common validation errors:

Error Code	Description
`missing_required_field`	Required field is missing
`invalid_url`	URL is not a valid HTTP/HTTPS URL
`invalid_slug`	Slug contains invalid characters
`invalid_email`	Email address is invalid
`value_too_long`	Field value exceeds maximum length
`value_too_short`	Field value is below minimum length

Error Logging

Log errors for debugging:

try {
  const response = await fetch('https://api.bouncy.ai/v1/links', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer bcy_live_pk_YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ url: 'https://example.com' })
  });

  if (!response.ok) {
    const error = await response.json();
    console.error('API Error:', {
      status: response.status,
      code: error.error?.code,
      message: error.error?.message,
      timestamp: new Date().toISOString()
    });
    throw new Error(error.error?.message || 'API request failed');
  }

  return response.json();
} catch (error) {
  // Log to error tracking service (Sentry, etc.)
  console.error('Request failed:', error);
  throw error;
}

Need Help?

If you encounter persistent errors:

Check the API Status Page
Review your API Dashboard for usage limits
Contact support at help.bouncy.ai

Get Started

Guides

Error Response Format

HTTP Status Codes

Common Errors

401 Unauthorized - Missing API Key

401 Unauthorized - Invalid API Key

403 Forbidden - Plan Upgrade Required

403 Forbidden - Quota Exceeded

404 Not Found

409 Conflict - Slug Already Exists

429 Too Many Requests - Rate Limit Exceeded

Rate Limiting

Rate Limit Headers

Rate Limits by Plan

Handling Rate Limits

Best Practices for Rate Limiting

Retry Logic

Validation Errors

Error Logging

Need Help?

​Error Response Format

​HTTP Status Codes

​Common Errors

​401 Unauthorized - Missing API Key

​401 Unauthorized - Invalid API Key

​403 Forbidden - Plan Upgrade Required

​403 Forbidden - Quota Exceeded

​404 Not Found

​409 Conflict - Slug Already Exists

​429 Too Many Requests - Rate Limit Exceeded

​Rate Limiting

​Rate Limit Headers

​Rate Limits by Plan

​Handling Rate Limits

​Best Practices for Rate Limiting

​Retry Logic

​Validation Errors

​Error Logging

​Need Help?

Error Response Format

HTTP Status Codes

Common Errors

401 Unauthorized - Missing API Key

401 Unauthorized - Invalid API Key

403 Forbidden - Plan Upgrade Required

403 Forbidden - Quota Exceeded

404 Not Found

409 Conflict - Slug Already Exists

429 Too Many Requests - Rate Limit Exceeded

Rate Limiting

Rate Limit Headers

Rate Limits by Plan

Handling Rate Limits

Best Practices for Rate Limiting

Retry Logic

Validation Errors

Error Logging

Need Help?