APIKey

API Key Error Codes

Copy page

This document describes all error codes related to API key authentication and validation in the Stayforge API system.

Table of Contents

1. Overview
2. Error Response Format
3. Error Codes
   • Authentication Errors
   • Verification Errors
   • Permission Errors
   • IP Restriction Errors
4. Error Code Reference

Overview

All API key-related errors follow a consistent format and are returned as JSON responses. Errors are categorized by HTTP status code:

• 401 Unauthorized: Authentication failures (missing or invalid API key)
• 403 Forbidden: Authorization failures (verified but not authorized)

Error Response Format

All error responses follow this structure:

Code
 
{
  "message": "Human-readable error message",
  "code": "error_code_string"
}

Example Error Response

Code
 
{
  "message": "X-API-Key header is required. Create an APIkey at https://dash.stayforge.io/settings/apikeys",
  "code": "missing_api_key"
}

Error Codes

Authentication Errors

These errors occur during the initial API key parsing and verification phase.

missing_api_key

• HTTP Status: 401 Unauthorized
• Description: The X-API-Key header is missing from the request
• Message: "X-API-Key header is required. Create an APIkey at https://dash.stayforge.io/settings/apikeys"
• When it occurs:
  • Request does not include the X-API-Key header
  • Header is present but empty
• How to fix:
  • Add the X-API-Key header to your request
  • Ensure the header value is not empty
  • Create an API key at https://dash.stayforge.io/settings/apikeys

invalid_api_key

• HTTP Status: 401 Unauthorized
• Description: The API key format is invalid or cannot be parsed
• Message: "Invalid API key: {error details}"
• When it occurs:
  • Invalid API key prefix (must be sk_org_ or sk_ten_)
  • Invalid API key format (missing dot separator)
  • Failed to decode Base58 payload or signature
  • Invalid HMAC signature (signature mismatch)
  • Failed to parse JSON payload
  • API key has expired (TTL check failed)
• How to fix:
  • Verify the API key is correctly copied
  • Ensure the API key has not expired
  • Generate a new API key if necessary
  • Check that the API key format matches: {prefix}{payload}.{signature}

Verification Errors

These errors occur when verifying the API key status with the Manage API.

apikey_verify_error

• HTTP Status: 403 Forbidden
• Description: Failed to verify the API key status with the Manage API
• Message: "API key verification failed: {error details}"
• When it occurs:
  • Network error when calling Manage API
  • Manage API returns non-2xx status code
  • Timeout when verifying API key
  • Manage API service unavailable
• How to fix:
  • Retry the request after a short delay
  • Check if the Manage API service is operational
  • Contact support if the issue persists

apikey_not_verified

• HTTP Status: 403 Forbidden
• Description: The API key exists but is not verified or is inactive
• Message: "API key is not verified or inactive"
• When it occurs:
  • API key verification returns an empty list
  • API key has been deactivated
  • API key is pending verification
• How to fix:
  • Verify the API key status in the dashboard
  • Activate the API key if it's inactive
  • Generate a new API key if necessary
  • Check API key settings at https://dash.stayforge.io/settings/apikeys

Permission Errors

These errors occur when the API key does not have sufficient permissions to access the requested resource.

apikey_insufficient_permissions

• HTTP Status: 403 Forbidden
• Description: The API key does not have the required permissions to access the requested resource
• Message:
  • "Insufficient permissions to access this resource" (generic)
  • Or detailed error message from permission verification (e.g., "Missing required permissions: cards")
• When it occurs:
  • API key lacks the required scope/permission for the endpoint
  • Permission verification fails
  • Network error when checking permissions
• How to fix:
  • Check the required permissions for the endpoint
  • Update the API key permissions in the dashboard
  • Ensure the API key has the correct scopes assigned
  • Review API key permissions at https://dash.stayforge.io/settings/apikeys

IP Restriction Errors

These errors occur when IP address restrictions are configured and the client IP is not in the allowed list.

ip_range_fetch_error

• HTTP Status: 403 Forbidden
• Description: Failed to retrieve the allowed IP ranges for the API key
• Message: "Failed to verify IP address restrictions. Please try again later."
• When it occurs:
  • Network error when calling Manage API to get IP ranges
  • Manage API returns non-2xx status code
  • Timeout when fetching IP ranges
  • Manage API service unavailable
• How to fix:
  • Retry the request after a short delay
  • Check if the Manage API service is operational
  • Contact support if the issue persists

ip_validation_error

• HTTP Status: 403 Forbidden
• Description: IP address validation failed due to an internal error
• Message: "IP address validation failed"
• When it occurs:
  • Invalid client IP address format
  • Invalid CIDR range format in allowed IP ranges
  • Error parsing IP addresses or CIDR ranges
• How to fix:
  • Verify the client IP address is valid
  • Check the allowed IP ranges configuration
  • Contact support if the issue persists

ip_not_allowed

• HTTP Status: 403 Forbidden
• Description: The client IP address is not in the allowed IP ranges list
• Message: "IP address {client_ip} is not in the allowed list. Go http://dash.stayforge.io/settings/apikeys to check your APIkey's allowed IP Ranges"
• When it occurs:
  • IP restrictions are configured for the API key
  • Client IP address does not match any allowed CIDR range
  • Request is coming from an unauthorized IP address
• How to fix:
  • Add your IP address to the allowed IP ranges
  • Update IP restrictions in the dashboard
  • Use an IP address that is in the allowed list
  • Configure IP ranges at https://dash.stayforge.io/settings/apikeys
  • Note: Empty IP ranges list means no restrictions (all IPs allowed)

Error Code Reference

Quick Reference Table

Error Code	HTTP Status	Category	Retryable
missing_api_key	401	Authentication	No
invalid_api_key	401	Authentication	No
apikey_verify_error	403	Verification	Yes
apikey_not_verified	403	Verification	No
apikey_insufficient_permissions	403	Permission	No
ip_range_fetch_error	403	IP Restriction	Yes
ip_validation_error	403	IP Restriction	No
ip_not_allowed	403	IP Restriction	No

Error Flow

The API key validation process follows this order:

1. Extract API Key → missing_api_key (if missing)
2. Parse & Verify → invalid_api_key (if invalid)
3. Verify Status → apikey_verify_error or apikey_not_verified
4. Check Permissions → apikey_insufficient_permissions
5. Check IP Ranges → ip_range_fetch_error, ip_validation_error, or ip_not_allowed

All checks (steps 3-5) are performed concurrently for better performance.

HTTP Status Code Guidelines

• 401 Unauthorized: The request lacks valid authentication credentials. The client should authenticate before retrying.
• 403 Forbidden: The request is authenticated but does not have permission to access the resource. The client should not retry with the same credentials.

Best Practices

1. Error Handling: Always check the code field for programmatic error handling
2. User Messages: Display the message field to end users
3. Retry Logic: Only retry requests for retryable errors (see table above)
4. Logging: Log both code and message for debugging purposes
5. Monitoring: Monitor error rates by error code to identify issues

Example Error Handling

Code
 
// JavaScript/TypeScript example
try {
  const response = await fetch('/api/endpoint', {
    headers: {
      'X-API-Key': apiKey
    }
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.code) {
      case 'missing_api_key':
      case 'invalid_api_key':
        // Authentication error - don't retry
        console.error('Authentication failed:', error.message);
        break;
        
      case 'apikey_verify_error':
      case 'ip_range_fetch_error':
        // Retryable error - retry with exponential backoff
        await retryWithBackoff(() => fetch('/api/endpoint', options));
        break;
        
      case 'apikey_insufficient_permissions':
        // Permission error - check API key permissions
        console.error('Permission denied:', error.message);
        break;
        
      case 'ip_not_allowed':
        // IP restriction - update IP ranges
        console.error('IP not allowed:', error.message);
        break;
        
      default:
        console.error('Unknown error:', error);
    }
  }
} catch (error) {
  console.error('Request failed:', error);
}

Code
 
// Go example
type APIError struct {
    Message string `json:"message"`
    Code    string `json:"code"`
}

func handleAPIError(resp *http.Response) error {
    var apiErr APIError
    if err := json.NewDecoder(resp.Body).Decode(&apiErr); err != nil {
        return err
    }
    
    switch apiErr.Code {
    case "missing_api_key", "invalid_api_key":
        return fmt.Errorf("authentication failed: %s", apiErr.Message)
    case "apikey_verify_error", "ip_range_fetch_error":
        // Retryable errors
        return &RetryableError{Err: apiErr}
    case "apikey_insufficient_permissions":
        return fmt.Errorf("permission denied: %s", apiErr.Message)
    case "ip_not_allowed":
        return fmt.Errorf("IP restriction: %s", apiErr.Message)
    default:
        return fmt.Errorf("unknown error: %s", apiErr.Message)
    }
}

---

Document Version: 1.0
Last Updated: 2024-12-19
Maintained By: Stayforge API Team