Error Codes

When an API request fails, Universal API returns standardized error codes to help you understand what went wrong. This document provides a comprehensive list of error codes and their meanings.

Error Response Format

When an error occurs, Universal API returns a response with the following structure:

{
  "success": false,
  "error": {
    "title": "Error",
    "detail": "Error message describing what went wrong",
    "code": "ERROR_CODE",
    "timestamp": "2025-04-06T22:36:00.000Z"
  },
  "meta": {
    "requestId": "req-1234567890",
    "statusCode": 400,
    "timestamp": "2025-04-06T22:36:00.000Z"
  }
}

The error object contains:

• title: A general category of the error
• detail: A specific message describing what went wrong
• code: A standardized error code that can be used for programmatic handling
• timestamp: The time when the error occurred

Common Error Codes

Authentication Errors

Error Code	HTTP Status	Description
UNAUTHORIZED	401	Authentication credentials are missing or invalid
FORBIDDEN	403	Authentication succeeded but the user doesn't have permission to access the resource
INVALID_CREDENTIALS	401	The provided userId or secretUniversalKey is invalid
EXPIRED_TOKEN	401	The authentication token has expired

Rate Limiting Errors

Error Code	HTTP Status	Description
RATE_LIMIT_EXCEEDED	429	The user has exceeded their rate limit
DAILY_LIMIT_EXCEEDED	429	The anonymous user has exceeded their daily request limit
CREDITS_REQUIRED	402	The user has no credits remaining for this operation

Resource Errors

Error Code	HTTP Status	Description
RESOURCE_NOT_FOUND	404	The requested resource (action, API key, etc.) was not found
ACTION_NOT_FOUND	404	The specified action ID does not exist
INVALID_ACTION_ID	400	The action ID format is invalid
ACTION_EXECUTION_ERROR	500	An error occurred while executing the action

Input Validation Errors

Error Code	HTTP Status	Description
INVALID_REQUEST	400	The request format is invalid or missing required fields
INVALID_PARAMETERS	400	One or more parameters have invalid values
MISSING_REQUIRED_PARAMETER	400	A required parameter is missing from the request
INVALID_JSON	400	The request body contains invalid JSON

Server Errors

Error Code	HTTP Status	Description
INTERNAL_ERROR	500	An unexpected error occurred on the server
SERVICE_UNAVAILABLE	503	The service is temporarily unavailable
EXTERNAL_SERVICE_ERROR	502	An error occurred in an external service
TIMEOUT	504	The request timed out

Action-Specific Errors

Error Code	HTTP Status	Description
ACTION_RUNTIME_ERROR	500	An error occurred in the action runtime
ACTION_TIMEOUT	504	The action execution timed out
INVALID_ACTION_CODE	400	The action code is invalid or contains syntax errors
MISSING_API_KEY	400	A required API key for an external service is missing

Error Handling Best Practices

When handling errors from Universal API:

1. Check the success field first to determine if the request was successful
2. Use the code field for programmatic handling rather than parsing the error message
3. Log the requestId for troubleshooting purposes
4. Implement appropriate retry logic for rate limiting and server errors
5. Display user-friendly messages based on the detail field

Example Error Handling

JavaScript Example

async function executeAction(actionId, params) {
  try {
    const response = await fetch(`https://api.universalapi.co/action/${actionId}`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Uni-userId': 'your-user-id',
        'X-Uni-secretUniversalKey': 'your-secret-key'
      },
      body: JSON.stringify(params)
    });
    
    const data = await response.json();
    
    if (!data.success) {
      // Handle error based on error code
      switch (data.error.code) {
        case 'RATE_LIMIT_EXCEEDED':
          console.log('Rate limit exceeded. Retrying after delay...');
          // Implement retry logic with exponential backoff
          break;
        case 'ACTION_NOT_FOUND':
          console.error(`Action ${actionId} not found`);
          break;
        case 'INVALID_PARAMETERS':
          console.error(`Invalid parameters: ${data.error.detail}`);
          break;
        default:
          console.error(`Error: ${data.error.detail}`);
      }
      return null;
    }
    
    return data.result;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}

Python Example

import requests
import time

def execute_action(action_id, params):
    try:
        response = requests.post(
            f'https://api.universalapi.co/action/{action_id}',
            headers={
                'X-Uni-userId': 'your-user-id',
                'X-Uni-secretUniversalKey': 'your-secret-key'
            },
            json=params
        )
        
        data = response.json()
        
        if not data.get('success'):
            error = data.get('error', {})
            error_code = error.get('code')
            
            # Handle error based on error code
            if error_code == 'RATE_LIMIT_EXCEEDED':
                print('Rate limit exceeded. Retrying after delay...')
                time.sleep(5)  # Wait 5 seconds before retrying
                return execute_action(action_id, params)  # Retry
            elif error_code == 'ACTION_NOT_FOUND':
                print(f'Action {action_id} not found')
            elif error_code == 'INVALID_PARAMETERS':
                print(f'Invalid parameters: {error.get("detail")}')
            else:
                print(f'Error: {error.get("detail")}')
            return None
        
        return data.get('result')
    except Exception as e:
        print(f'Network error: {e}')
        return None