Troubleshooting

Common issues, error codes, and solutions for Sync As A Service integration.

---

Error Codes

Error Structure

All errors follow this format:

{
  code: "rate_limited",           // Machine-readable error code
  message: "Too many requests",   // Human-readable message
  details: { retryAfter: 60 }     // Optional additional context
}

Authentication Errors

Code	Description	Action
auth_required	User not authenticated	Widget shows login automatically
token_expired	Access token expired	SDK refreshes automatically
invalid_token	Token is invalid	User needs to re-authenticate

Connection Errors

Code	Description	Action
invalid_credentials	Retailer login failed	Re-enter username/password
mfa_required	MFA verification needed	Enter verification code
retailer_unavailable	Retailer site is down	Try again later
connection_timeout	Connection timed out	Check internet connection

Sync Errors

Code	Description	Action
sync_failed	Sync encountered error	Check sync session for details
no_orders_found	No qualifying orders	Normal - retailer has no orders
session_expired	Retailer session expired	User needs to reconnect

Rate Limiting

Code	Description	Action
rate_limited	Too many requests	Wait 60 seconds, then retry
too_many_attempts	Too many failed login attempts	Wait 5 minutes

System Errors

Code	Description	Action
network_error	Network request failed	Check connection, retry
server_error	Internal server error	Retry with exponential backoff
service_unavailable	Service temporarily down	Try again in 5 minutes

---

Widget Issues

Widget Not Loading

Symptoms: Blank space where widget should be

Solutions:

1. Check script URL

   <!-- Correct -->
   <script src="https://sync.brandclub.com/sync-sdk/latest/sdk.umd.js"></script>
   
   <!-- Wrong -->
   <script src="https://sync.brandclub.com/sync-sdk/sdk.umd.js"></script>
   ❌

2. Check browser console for errors

   Open DevTools (F12) → Console tab → Look for errors

3. Verify container exists

   // Make sure container exists before init
   const container = document.getElementById("sync-widget");
   if (!container) {
     console.error("Container #sync-widget not found!");
   }

4. Check script load order

   <!-- SDK must load BEFORE init() -->
   <script src="https://sync.brandclub.com/sync-sdk/latest/sdk.umd.js"></script>
   <script>
     // This works ✓
     BrandclubSync.init({ ... });
   </script>

Widget Shows "Widget not built yet"

Cause: SDK CDN file not found

Solution: Contact Sync As A Service support - this indicates a deployment issue.

Widget Shows Error Screen

Check:

• Client ID is correct

• Network connection is working

• Browser console for specific error

Authentication Issues

"Invalid client" Error

Cause: Client ID not recognized

Solutions:

1. Verify client ID matches registration

2. Check for typos

3. Ensure client is active (not disabled)

// Double-check your client ID
BrandclubSync.init({
  clientId: "bc_your_app_id", // ← Must exactly match registration
  container: "#sync-widget",
});

OAuth Redirect Loop

Symptoms: Page keeps redirecting back and forth

Cause: Redirect URI mismatch

Solution:

1. Check registered redirect URI: https://yourapp.com/callback

2. Verify actual callback URL matches exactly

3. Ensure /callback route exists and loads SDK

// On /callback page
BrandclubSync.init({
  clientId: "bc_your_app_id",
  container: "#sync-widget",
});
// SDK automatically processes OAuth callback

Phone Number Not Working

Cause: Invalid phone format or account doesn't exist

Solutions:

1. Format: Must include country code

   • ✓ [phone]

   • ✓ [phone]

   • ✓ 1-555-0100

   • ✗ 555-0100 (missing country code)

2. Test accounts: Use demo client for testing

   • Phone: [phone]

   • OTP: 424242

Connection Issues

Can't Connect Retailer

Symptoms: Credentials form returns error

Common causes:

1. Invalid credentials - User entered wrong username/password

   • Solution: User must re-enter correct credentials

2. Retailer site down - Target retailer is experiencing issues

   • Solution: Try again later, check retailer's website status

3. MFA not entered - Retailer requires additional verification

   • Solution: Widget shows MFA prompt automatically

Connection Says "Expired"

Cause: Retailer session expired (common after 30-90 days)

Solution: User needs to reconnect the retailer (re-enter credentials)

// Detect expired connections
onStateChange: (state) => {
  if (state === "error") {
    // Check if it's an expiry error
    // Prompt user to reconnect
  }
};

Sync Issues

Orders Not Appearing

Check:

1. Sync completed successfully

   onSync: (result) => {
     console.log("Sync found", result.ordersFound, "orders");
     if (result.ordersFound === 0) {
       // Retailer has no qualifying orders
     }
   };

2. Correct date range

   • We sync orders from the last 90 days by default

3. Qualifying purchases

   • Some retailers only track online orders

   • In-store purchases may not be available

4. Permissions

   • Contact Sync As A Service support if you suspect a permissions issue

Sync Stuck at "Scanning"

Cause: MFA required but not completed

Solution: Check widget state - it should show MFA prompt

Sync Shows "Error"

Check sync session for details:

const response = await fetch(
  `https://sync.brandclub.com/sync/sessions/${syncBatchId}`,
  { headers: { Authorization: `Bearer ${token}` } }
);

const session = await response.json();
console.log("Error:", session.retailerSyncSessions[0].errorMessage);

API Issues

401 Unauthorized

Cause: Missing or invalid token

Solutions:

1. Check token is included:

   // ✓ Correct
   headers: {
     Authorization: `Bearer ${token}`;
   }
   
   // ✗ Wrong
   headers: {
     Authorization: token;
   }

2. Verify token hasn't expired

3. Ensure you're using the correct client ID

403 Forbidden

Cause: Access not configured for this endpoint

Solution: Contact Sync As A Service support—your client may need additional access configured.

404 Not Found

Common causes:

1. Wrong endpoint URL

   • ✓ https://sync.brandclub.com/sync/orders

   • ✗ https://sync.brandclub.com/orders (missing /sync prefix)

2. Resource doesn't exist

   • Check retailer ID is correct

   • Check order ID exists

429 Rate Limited

Cause: Too many requests

Solution: Implement exponential backoff (see Integration Guides)

CORS Issues

"No Access-Control-Allow-Origin" Error

Cause: Making API calls directly from browser

Solution: Proxy through your backend

// ❌ Don't call Sync As A Service API directly from browser
fetch("https://sync.brandclub.com/sync/orders", {
  headers: { Authorization: `Bearer ${token}` },
});

// ✓ Proxy through your backend
fetch("/api/orders", {
  headers: { Authorization: `Bearer ${sessionId}` },
});

// Backend forwards to Sync As A Service
app.get("/api/orders", async (req, res) => {
  const brandclubToken = req.session.brandclub_token;
  const orders = await fetch("https://sync.brandclub.com/sync/orders", {
    headers: { Authorization: `Bearer ${brandclubToken}` },
  });
  res.json(await orders.json());
});

Integration Issues

Widget Doesn't Fit Container

Solution: Widget auto-resizes. Ensure container has no height restrictions:

#sync-widget {
  width: 100%;
  min-height: 400px; /* Optional minimum */
  /* Don't set max-height */
}

Multiple Widgets on Same Page

Not supported. Only initialize once per page:

// ❌ Don't do this
BrandclubSync.init({ container: "#widget1" });
BrandclubSync.init({ container: "#widget2" }); // Second instance won't work

// ✓ Use one widget
BrandclubSync.init({ container: "#widget1" });

Debugging Tips

Enable Verbose Logging

// Check browser console for detailed logs
// SDK logs important events automatically

Test with Demo Client

BrandclubSync.init({
  clientId: "bc_example_rewards_app_demo", // Demo client for testing
  container: "#sync-widget",
});

Inspect Network Requests

1. Open DevTools → Network tab

2. Filter by "sync.brandclub.com"

3. Check request/response for errors

Check CloudFront Cache

# Force bypass cache to test origin
curl -H "Cache-Control: no-cache" https://sync.brandclub.com/sync-sdk/latest/sdk.umd.js

Getting Help

Error Not Listed Here?

1. Check browser console for error details

2. Check the Error Codes section above for explanations

3. Review API Reference for endpoint documentation

4. Contact Sync As A Service support with:

   • Client ID

   • Error message/code

   • Browser console logs

   • Network request/response (if API issue)

Performance Issues?

• Review Integration Guides for optimization tips

• Check rate limits aren't being exceeded

• Verify caching is implemented

FAQ

Q: Can I customize the widget UI? A: The widget is fully styled. Custom themes (light/dark) are supported.

Q: How often should I sync? A: We auto-sync users weekly. You can trigger manual syncs, but respect rate limits (10/hour per retailer).

Q: Can users connect the same retailer in multiple apps? A: Yes! That's the portable identity feature - one connection works everywhere.

Q: What if a retailer's API changes? A: Sync As A Service maintains integrations. Your app continues working without changes.

Q: Can I sync historical orders? A: We sync orders from the last 90 days by default.

Q: What about in-store purchases? A: Varies by retailer. Most online-only retailers provide online orders only.