OnlyOneAPI - One API, Infinite Possibilities

Error Handling Guide

Build robust applications with proper error handling and retry strategies

Common Error Codes

HTTP status codes you may encounter

Code	Name	Description
400	Bad Request	The request was invalid or cannot be served
401	Unauthorized	Authentication credentials were missing or incorrect
403	Forbidden	The request is valid but the server is refusing access
404	Not Found	The requested resource could not be found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	An error occurred on the server
503	Service Unavailable	The service is temporarily unavailable

Error Response Format

Standard error response structure

All error responses from OnlyOneAPI follow a consistent format to help you handle them programmatically.

{
"error": {
 "code":"RATE_LIMIT_EXCEEDED",
 "message":"You have exceeded the rate limit of 100 requests per minute",
 "type":"rate_limit_error",
 "details": {
  "limit": 100,
  "reset_at":"2025-07-02T12:30:00Z",
  "current_usage": 101
  }
 },
"request_id":"req_abc123def456"
}

Handling Errors in Your Code

Examples in different languages

JavaScript / Node.js

try {
 const response = await client.text.analyze({
  text:"Sample text"
 });
 console.log(response);
} catch (error) {
 if (error.status === 429) {
  // Handle rate limit
  const resetTime = error.details.reset_at;
  console.log(`Rate limited. Retry after ${resetTime}`);
 } else if (error.status === 401) {
  // Handle authentication error
  console.error("Invalid API key");
 } else {
  // Handle other errors
  console.error(`Error: ${error.message}`);
 }
}

Python

from onlyoneapi import APIError

try:
  response = client.text.analyze(text="Sample text")
  print(response)
except APIError as e:
  if e.status_code == 429:
    # Handle rate limit
    reset_time = e.details.get('reset_at')
    print(f"Rate limited. Retry after {reset_time}")
  elif e.status_code == 401:
    # Handle authentication error
    print("Invalid API key")
  else:
    # Handle other errors
    print(f"Error: {e.message}")

Retry Strategies

Implementing automatic retries

Exponential Backoff

Use exponential backoff for retrying failed requests, especially for 429 and 5xx errors.

async function makeRequestWithRetry(request, maxRetries = 3) {
 let lastError;
 
 for (let i = 0; i < maxRetries; i++) {
  try {
   return await request();
  } catch (error) {
   lastError = error;
   
   // Only retry on specific errors
   if (error.status !== 429 && error.status < 500) {
    throw error;
   }
   
   // Calculate delay: 2^i * 1000ms (1s, 2s, 4s...)
   const delay = Math.pow(2, i) * 1000;
   await new Promise(resolve => setTimeout(resolve, delay));
  }
 }
 
 throw lastError;
}

Best Practices

Recommendations for robust error handling

Always implement retry logic

Network issues and temporary failures happen. Implement automatic retries with backoff.

Log errors with context

Include request IDs and relevant parameters in your error logs for debugging.

Handle rate limits gracefully

Respect rate limits and implement queuing or backoff when limits are reached.

Validate inputs client-side

Catch errors early by validating inputs before making API calls.

Implement circuit breakers

For high-traffic applications, use circuit breakers to prevent cascading failures.

Need Help?

Check out our examples or contact support if you need help implementing error handling.

View Examples Contact Support