Gashapon Machine Integration

Error Handling Strategies

Error Handling

Proper error handling is crucial for a smooth user experience and system reliability. This section covers common error scenarios and strategies for handling them effectively.

Common Error Scenarios

Insufficient Points

User attempts to use the gashapon machine but doesn't have enough points in their account.

Handling Strategy:
  • Return a specific error code (e.g., ERROR_INSUFFICIENT_POINTS)
  • Show a clear error message in the app explaining the issue
  • Provide a direct option to purchase more points
  • Log the attempted transaction for analytics

Expired QR Code

QR code has exceeded its validity timeframe (typically 5 minutes).

Handling Strategy:
  • Return expiration error (ERROR_QR_EXPIRED)
  • Prompt user to generate a new QR code
  • Include clear messaging about the expiration time limit
  • Log attempt to use expired code for security monitoring

Network Issues

Connection problems between the machine, backend, or app during transaction.

Handling Strategy:
  • Implement retry logic with exponential backoff
  • Provide clear error messages about connection issues
  • Consider offline fallback options where possible
  • Ensure transaction state is consistent after reconnection

Machine Malfunction

The gashapon machine experiences a mechanical failure after points are deducted.

Handling Strategy:
  • Automatically refund points to user account
  • Log machine errors with detailed diagnostics
  • Notify maintenance staff about the issue
  • Send push notification to user about the refund

Double-Spend Attempts

User attempts to use the same QR code multiple times.

Handling Strategy:
  • Track used QR codes in database with timestamps
  • Implement one-time-use validation for all QR codes
  • Return specific error (ERROR_CODE_ALREADY_USED)
  • Flag accounts with multiple double-spend attempts for review

Error Handling Flowchart

flowchart TD A[Machine Scans QR Code] --> B{Valid Signature?} B -->|No| C[Reject: Invalid QR] B -->|Yes| D{Expired?} D -->|Yes| E[Reject: Expired QR] D -->|No| F{Already Used?} F -->|Yes| G[Reject: Already Used] F -->|No| H{Sufficient Points?} H -->|No| I[Reject: Insufficient Points] H -->|Yes| J[Deduct Points] J --> K{Machine Command Success?} K -->|No| L[Refund Points] K -->|Yes| M[Complete Transaction] L --> N[Report Error]

Standard Error Response Structure

API Error Response

{
  "status": "error",
  "error_code": "ERROR_INSUFFICIENT_POINTS",
  "message": "User doesn't have enough points",
  "transaction_id": "tx_12345",
  "timestamp": "2023-07-14T15:30:45Z",
  "details": {
    "required_points": 50,
    "available_points": 25
  }
}

Always include:

  • Standardized error codes
  • Human-readable messages
  • Timestamp for tracking
  • Transaction ID for support

App Error Display Guidelines

User-Friendly Messages

Use clear, non-technical language that explains:

  • What happened
  • Why it happened
  • What the user can do next
Actionable Solutions

Always provide a clear next step:

  • "Buy More Points" button for insufficient points
  • "Generate New Code" for expired QR codes
  • "Try Again" for network errors
  • "Contact Support" for persistent issues
Error Tracking

Implement client-side logging:

  • Log errors with context
  • Include device information
  • Track error frequency
  • Set up alerts for critical issues