Error Handling

Understanding error responses, rate limits, and best practices for robust integrations

Standard Error Format

All API errors follow a consistent JSON format to help with programmatic error handling:

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or expired",
  "code": 401,
  "timestamp": "2026-01-14T12:00:00Z",
  "details": {
    "suggestion": "Please check your API key and ensure it's active"
  }
}

Error Response Fields

error: Machine-readable error code for programmatic handling
message: Human-readable error description
code: HTTP status code
timestamp: When the error occurred (ISO 8601 format)
details: Additional context and suggestions (when available)

Common Error Codes

400Bad Request Errors

invalid_request

The request is malformed or missing required parameters.

{"error": "invalid_request", "message": "Missing required field: query", "code": 400}

Solution: Ensure all required fields are included in your request body.

invalid_parameter

A parameter has an invalid value or format.

{"error": "invalid_parameter", "message": "limit must be between 1 and 50", "code": 400}

Solution: Check parameter constraints in the API reference.

401Authentication Errors

missing_api_key

No API key was provided in the request headers.

{"error": "missing_api_key", "message": "API key required", "code": 401}

Solution: Include the X-API-Key header with your API key.

invalid_api_key

The provided API key is invalid, expired, or revoked.

{"error": "invalid_api_key", "message": "The provided API key is invalid", "code": 401}

Solution: Generate a new API key or verify your existing key is correct.

403Rate Limit Errors

rate_limit_exceeded

You've exceeded your daily or per-minute rate limit.

{"error": "rate_limit_exceeded", "message": "Daily limit of 1000 requests exceeded", "code": 403}

Solution: Wait until your limit resets or upgrade your plan for higher limits.

404Not Found Errors

resource_not_found

The requested resource (product, merchant, etc.) was not found.

{"error": "resource_not_found", "message": "Product with ID 'prod_123' not found", "code": 404}

Solution: Verify the resource ID is correct and the resource exists.

500Server Errors

internal_error

An unexpected error occurred on our servers.

{"error": "internal_error", "message": "An unexpected error occurred", "code": 500}

Solution: Retry your request after a brief delay. Contact support if the issue persists.

Rate Limits

Current Limits

Free Tier1,000 requests/day

Per-minute limitNone (fair use)

EnterpriseCustom limits

Rate Limit Headers

Check these response headers to monitor your usage:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1641859200

Error Handling Strategies

Retry Logic

async function retryRequest(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code < 500 || i === maxRetries - 1) {
        throw error;
      }
      await sleep(1000 * Math.pow(2, i)); // Exponential backoff
    }
  }
}

• Retry on 5xx errors and network issues
• Don't retry on 4xx errors (client errors)
• Use exponential backoff to avoid overwhelming servers
• Limit the number of retry attempts

Graceful Degradation

try {
  const results = await searchProducts(query);
  return results;
} catch (error) {
  if (error.code === 403) {
    // Rate limited - use cached results
    return getCachedResults(query);
  } else if (error.code >= 500) {
    // Server error - show user-friendly message
    return { error: 'Service temporarily unavailable' };
  }
  throw error; // Re-throw client errors
}

• Provide fallback functionality when possible
• Cache responses for offline scenarios
• Show meaningful error messages to users
• Log errors for debugging and monitoring

Monitoring & Debugging

Check Usage Statistics

// Check your API usage regularly
const usage = await fetch('/api/v1/auth/usage', {
  headers: { 'X-API-Key': apiKey }
});

const data = await usage.json();
console.log(`Used ${data.requestsToday}/${data.dailyLimit} requests`);

if (data.requestsToday > data.dailyLimit * 0.9) {
  console.warn('Approaching rate limit');
}

Error Logging

function logError(error, context) {
  console.error('API Error:', {
    error: error.error,
    message: error.message,
    code: error.code,
    timestamp: error.timestamp,
    context: context,
    userAgent: navigator.userAgent
  });

  // Send to monitoring service
  // analytics.track('api_error', { ... });
}

Need Help?

Support Channels

• Email: support@abbababa.com
• Response time: 24-48 hours
• Discord community (coming soon)

When Contacting Support

• Include the error message and code
• Provide the timestamp when error occurred
• Share your API key (last 4 characters only)
• Describe what you were trying to accomplish