Error Handling

Complete reference for Sharokey API error codes and responses when using our official SDKs.

📋 Overview

Our SDKs automatically handle all error scenarios and provide structured error objects. This reference shows the error formats you'll receive and how to handle them effectively.

Official SDKs:

• CLI C# Tool - Cross-platform command-line interface
• JavaScript SDK - For Node.js and modern web applications
• JavaScript CDN - Simple browser integration
• Python SDK - Async Python client

🔴 Error Response Format

All API errors follow a consistent JSON structure that our SDKs parse automatically:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "field_name",
      "value": "invalid_value",
      "additional_context": "More information"
    }
  },
  "timestamp": "2025-01-14T10:30:00Z",
  "request_id": "req_abcd1234efgh5678"
}

🚨 Authentication Errors

Invalid Token

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_ERROR",
    "message": "Token is invalid or expired"
  }
}

Common Causes:

• Token not configured in SDK
• Malformed or corrupted token
• Token has expired

SDK Handling: All SDKs detect authentication errors and provide clear feedback on token issues.

Insufficient Permissions

{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Insufficient permissions for this operation",
    "details": {
      "required_scope": "secrets:create",
      "token_scopes": ["secrets:read", "stats:read"]
    }
  }
}

Solution: Use a token with appropriate scopes for your operations.

⚠️ Validation Errors

Content Validation

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The content field is required",
    "details": {
      "content": ["The content field is required"],
      "expiration": ["Must be between 1 and 1000 hours"]
    }
  }
}

Common Validation Issues:

• content: Secret content cannot be empty
• hours: Must be between 1 and 1000 hours
• maximum_views: Must be between 1 and 10
• description: Maximum 255 characters
• password: Minimum 4 characters if provided

Attachment Errors

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "The total size of the attachments must be smaller than 10MB"
  }
}

File Limits:

• Maximum attachments: 10 files per secret
• Total size limit: 10MB per secret
• Supported extensions: pdf, jpg, jpeg, png, docx, txt

🔍 Resource Errors

Secret Not Found

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Secret not found or expired"
  }
}

Common Causes:

• Secret was deleted
• Secret expired naturally
• Wrong slug provided
• No permission to access secret

🚦 Rate Limiting Errors

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests. Please try again later."
  }
}

Rate Limits:

• Authentication: 10 requests per minute
• Secrets operations: 30 requests per minute
• Company token requests: 5 requests per minute

SDK Handling: All SDKs implement automatic retry logic with exponential backoff.

💰 Quota Errors

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "You have reached the maximum allowed secrets for your current plan."
  }
}

Solution: Upgrade your plan or wait for quota reset.

🖥️ Server Errors

Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "An internal server error occurred",
    "details": {
      "error_id": "err_abcd1234",
      "support_message": "Please contact support with this error ID"
    }
  }
}

Service Unavailable

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "details": {
      "retry_after": 300,
      "maintenance_window": false
    }
  }
}

🛠️ SDK Error Handling

CLI C# Error Handling

# The CLI provides clear error messages and exit codes
sharokey create "content" --hours 25000
# Error: Hours must be between 1 and 1000 (exit code 1)

# JSON output for scripting
sharokey create "content" --hours 25000 --json
# {"success": false, "error": {"code": "VALIDATION_ERROR", ...}}

JavaScript SDK Error Handling

try {
  const secret = await client.createSecret("content", {
    hours: 25000  // Invalid
  });
} catch (error) {
  console.log(error.code);        // "VALIDATION_ERROR"
  console.log(error.message);     // Human readable message
  console.log(error.details);     // Validation details
  
  // Handle specific errors
  if (error.code === 'QUOTA_EXCEEDED') {
    console.log('Upgrade your plan to create more secrets');
  }
}

Python SDK Error Handling

try:
    secret = await client.create("content", hours=25000)
except sharokey.ValidationError as e:
    print(f"Validation failed: {e.details}")
except sharokey.QuotaExceededError as e:
    print(f"Quota exceeded: {e.message}")
except sharokey.SharokeyError as e:
    print(f"API error: {e.code} - {e.message}")

🔧 Error Handling Best Practices

Graceful Degradation

JavaScript SDK

async function createSecretWithFallback(content, options) {
  try {
    return await client.createSecret(content, options);
  } catch (error) {
    if (error.code === 'QUOTA_EXCEEDED') {
      // Fallback: Store locally or queue for later
      return await storeLocally(content, options);
    }
    throw error; // Re-throw other errors
  }
}

Python SDK

async def create_secret_with_retry(content, **options):
    max_retries = 3
    for attempt in range(max_retries):
        try:
            return await client.create(content, **options)
        except sharokey.RateLimitError as e:
            if attempt < max_retries - 1:
                await asyncio.sleep(2 ** attempt)  # Exponential backoff
                continue
            raise
        except sharokey.SharokeyError:
            raise  # Don't retry on other errors

Error Logging

function logSharokeyError(error, context = {}) {
  const logEntry = {
    timestamp: new Date().toISOString(),
    level: 'ERROR',
    source: 'sharokey-sdk',
    error: {
      code: error.code,
      message: error.message,
      details: error.details
    },
    context
  };
  
  console.error(JSON.stringify(logEntry));
  
  // Alert on critical errors
  if (error.code === 'INTERNAL_ERROR') {
    notifySupport(logEntry);
  }
}

User-Friendly Messages

function getErrorMessage(error) {
  const messages = {
    'VALIDATION_ERROR': 'Please check your input and try again.',
    'QUOTA_EXCEEDED': 'You\'ve reached your plan limit. Consider upgrading.',
    'RATE_LIMIT_EXCEEDED': 'Too many requests. Please wait a moment.',
    'NOT_FOUND': 'The secret you\'re looking for doesn\'t exist or has expired.',
    'AUTHENTICATION_ERROR': 'Please check your API token configuration.'
  };
  
  return messages[error.code] || 'An unexpected error occurred. Please try again.';
}

🔗 Related Documentation

• Authentication - Secure token management and setup
• Rate Limits - Understanding API usage limits
• CLI C# Documentation - Command-line error handling
• JavaScript SDK - Browser and Node.js error handling
• Python SDK - Async error handling patterns

---

All SDKs implement automatic error handling, retry logic, and provide structured error objects for easy debugging.