PortfolioAbout This Article
Network issues and API rate limits mean sync failures are unavoidable. Therefore, we need to design recovery methods for errors. This article explains error patterns and their solutions.
Types of Sync Failures
Error Pattern Classification
| Pattern | Cause | Frequency | Urgency |
|---|---|---|---|
| Connection error | Network failure, API down | Low | High |
| Timeout | Processing delay, overload | Somewhat low | Medium |
| Auth error | Token expired, insufficient permissions | Low | High |
| Rate limit | API call limit exceeded | Medium | Low |
| Data error | Invalid format, missing required fields | Medium | Medium |
| Duplicate error | Conflict with existing data | Somewhat high | Low |
Connection error
CauseNetwork failure, API down
FrequencyLow
UrgencyHigh
Timeout
CauseProcessing delay, overload
FrequencySomewhat low
UrgencyMedium
Auth error
CauseToken expired, insufficient permissions
FrequencyLow
UrgencyHigh
Rate limit
CauseAPI call limit exceeded
FrequencyMedium
UrgencyLow
Data error
CauseInvalid format, missing required fields
FrequencyMedium
UrgencyMedium
Duplicate error
CauseConflict with existing data
FrequencySomewhat high
UrgencyLow
Error Patterns and Solutions
Pattern 1: POS API Connection Error
| Item | Content |
|---|---|
| Situation | API connection to POS system fails |
| Cause examples | POS server down, network failure, under maintenance |
Situation
ContentAPI connection to POS system fails
Cause examples
ContentPOS server down, network failure, under maintenance
Connection Error Response Policy
Keep Shopify registration successful
Maintain main registration process
Skip POS sync
Log error, notify admin
Re-sync later
Execute re-sync manually or automatically
Customer impact: Normal use online. Guide store use with "Please wait a moment"
Pattern 2: Data Format Error
| Item | Content |
|---|---|
| Situation | POS API returns data format error |
| Cause examples | Required field empty, phone number format invalid, address too long |
Situation
ContentPOS API returns data format error
Cause examples
ContentRequired field empty, phone number format invalid, address too long
Data Error Response Policy
Log error details
Identify which field has the problem
Attempt auto-fix
If possible, fix and retry / If not, notify admin
| Auto-fix Example | Processing |
|---|---|
| Phone number | Remove hyphens |
| Address | Truncate to fit character limit |
| Empty field | Set default value |
Phone number
ProcessingRemove hyphens
Address
ProcessingTruncate to fit character limit
Empty field
ProcessingSet default value
Pattern 3: Duplicate Error
| Item | Content |
|---|---|
| Situation | 'This email address is already registered' error |
| Cause | Existing store member registers online, or duplicate registration due to sync timing |
Situation
Content'This email address is already registered' error
Cause
ContentExisting store member registers online, or duplicate registration due to sync timing
Duplicate Error Response Policy
Attempt to link with existing customer
Search existing customer by email address
Linking result
Success -> Update existing customer's member number / Failure -> Record potential duplicate
Admin reviews and merges
Combine point balances, integrate purchase history, invalidate old record
Recovery Mechanism
Automatic Retry
| Attempt | Wait Time | Next Action |
|---|---|---|
| 1st failure | 2 seconds | Retry |
| 2nd failure | 4 seconds | Retry |
| 3rd failure | 8 seconds | Retry |
| 4th failure | - | Give up and log error |
1st failure
Wait Time2 seconds
Next ActionRetry
2nd failure
Wait Time4 seconds
Next ActionRetry
3rd failure
Wait Time8 seconds
Next ActionRetry
4th failure
Wait Time-
Next ActionGive up and log error
Exponential backoff: Doubling wait time reduces server load
| Error Type | Retry | Reason |
|---|---|---|
| Connection error | Yes | Possibly temporary failure |
| Timeout | Yes | Possibly temporary overload |
| Auth error | No | Retry yields same result |
| Data format error | No | Data fix required |
| Duplicate error | No | Different response needed |
Connection error
RetryYes
ReasonPossibly temporary failure
Timeout
RetryYes
ReasonPossibly temporary overload
Auth error
RetryNo
ReasonRetry yields same result
Data format error
RetryNo
ReasonData fix required
Duplicate error
RetryNo
ReasonDifferent response needed
Managing Unsynced Data
| Customer ID | Shopify | POS Sync | CRM Sync | Notes |
|---|---|---|---|---|
| 12345 | Success | Success | Success | - |
| 12346 | Success | Failed | Success | Needs re-sync |
| 12347 | Success | Success | Skipped | - |
12345
ShopifySuccess
POS SyncSuccess
CRM SyncSuccess
Notes-
12346
ShopifySuccess
POS SyncFailed
CRM SyncSuccess
NotesNeeds re-sync
12347
ShopifySuccess
POS SyncSuccess
CRM SyncSkipped
Notes-
Admin panel verification method:
- Filter by "POS sync failed"
- Check error content
- Retry with "Re-sync" button
Admin Tools
Sync Status Check
| Item | Count | Action |
|---|---|---|
| Synced | 1,234 | - |
| Unsynced (POS) | 5 | View details |
| Unsynced (CRM) | 2 | View details |
Synced
Count1,234
Action-
Unsynced (POS)
Count5
ActionView details
Unsynced (CRM)
Count2
ActionView details
| Customer ID | Name | Error Type | Time |
|---|---|---|---|
| 12346 | Taro Yamada | POS connection error | 10:30 |
| 12350 | Hanako Suzuki | Data format error | 10:25 |
12346
NameTaro Yamada
Error TypePOS connection error
Time10:30
12350
NameHanako Suzuki
Error TypeData format error
Time10:25
Operation: "Batch re-sync unsynced" button processes all targets at once
Re-sync Function
Select targets
Select unsynced customers from list (individual or batch)
Execute re-sync
Run sync process again with "Re-sync" button
Check results
Verify success/failure results
Continue response
If still failing, check error details and respond
Error Log Design
Information to Record
| Item | Content | Purpose |
|---|---|---|
| Timestamp | Error occurrence time | Chronological analysis |
| Customer ID | Target customer | Tracking and retry |
| Sync target | POS/CRM etc. | Identify failure location |
| Error type | Connection/Auth/Data etc. | Determine response method |
| Error details | API response etc. | Cause investigation |
| Retry count | How many attempts | Escalation decision |
Timestamp
ContentError occurrence time
PurposeChronological analysis
Customer ID
ContentTarget customer
PurposeTracking and retry
Sync target
ContentPOS/CRM etc.
PurposeIdentify failure location
Error type
ContentConnection/Auth/Data etc.
PurposeDetermine response method
Error details
ContentAPI response etc.
PurposeCause investigation
Retry count
ContentHow many attempts
PurposeEscalation decision
Log Example
| Field | Value | Description |
|---|---|---|
| timestamp | 2024-01-15T10:30:00Z | Error occurrence time |
| level | error | Log level |
| event | pos_sync_failed | Event type |
| customer_id | 12346 | Target customer ID |
| customer_email | yamada@example.com | Customer email |
| sync_target | pos | Target system |
| error_type | connection_error | Error type |
| error_message | Connection timed out after 15000ms | Error details |
| retry_count | 4 | Retry count |
| will_retry | false | Whether additional retry |
| shopify_sync | success | Shopify sync result |
| crm_sync | success | CRM sync result |
timestamp
Value2024-01-15T10:30:00Z
DescriptionError occurrence time
level
Valueerror
DescriptionLog level
event
Valuepos_sync_failed
DescriptionEvent type
customer_id
Value12346
DescriptionTarget customer ID
customer_email
Valueyamada@example.com
DescriptionCustomer email
sync_target
Valuepos
DescriptionTarget system
error_type
Valueconnection_error
DescriptionError type
error_message
ValueConnection timed out after 15000ms
DescriptionError details
retry_count
Value4
DescriptionRetry count
will_retry
Valuefalse
DescriptionWhether additional retry
shopify_sync
Valuesuccess
DescriptionShopify sync result
crm_sync
Valuesuccess
DescriptionCRM sync result
Monitoring and Alerts
Alert Conditions
| Condition | Alert Level | Notification Target |
|---|---|---|
| POS sync failures exceed 5/hour | Warning | Slack notification |
| POS sync fails continuously for 10+ minutes | Critical | Phone/Email |
| Unsynced data exceeds 100 items | Warning | Daily report |
| Auth error occurs | Critical | Immediate notification |
POS sync failures exceed 5/hour
Alert LevelWarning
Notification TargetSlack notification
POS sync fails continuously for 10+ minutes
Alert LevelCritical
Notification TargetPhone/Email
Unsynced data exceeds 100 items
Alert LevelWarning
Notification TargetDaily report
Auth error occurs
Alert LevelCritical
Notification TargetImmediate notification
Dashboard
| Sync Target | Success Rate (Last 24 Hours) |
|---|---|
| POS | 99.2% |
| CRM | 99.8% |
| Overall | 99.5% |
POS
Success Rate (Last 24 Hours)99.2%
CRM
Success Rate (Last 24 Hours)99.8%
Overall
Success Rate (Last 24 Hours)99.5%
Error trend: Graph error occurrence count over time to understand trends
Recent errors: 10:30 Connection error 1 case -> Resolved by auto-retry
Benefits of This Design
Availability
- Overall service continues despite some errors
- Auto-retry recovers from temporary failures
- Quick awareness when manual response needed
Operational Efficiency
- Automatic error detection and notification
- Easy re-sync from admin panel
- Rich logs for cause investigation
Customer Experience
- Basic service continues despite errors
- Minimized time to problem resolution
- Transparent status reporting possible