Best Practices

Validate Before You Upload

• Double-check your data against the schema every time.
• Use the /entities/schemas API to fetch the latest field definitions.
• If validation fails, check the error message and fix the fields accordingly.

Keep Page Size Manageable

• Send data in a paginated manner of 1,000 records or fewer — this keeps things fast and reliable.
• Use a unique pageNumber for each upload. Reusing a number will overwrite previous data.
• Group your data logically — users first, then groups, group-users, and so on.

Handle Errors Gracefully

• Retry failed requests with exponential backoff (especially for 5xx errors or timeouts).
• Always log the error responses — they help pinpoint what went wrong.
• If a sync is off-track, cancel it early instead of waiting till the end.

# Sample retry logic
for attempt in range(max_retries):
    try:
        return client.upload_snapshot_data(sync_id, entity, data, page_number)
    except Exception as e:
        if attempt == max_retries - 1:
            raise
        time.sleep(2 ** attempt)  # Exponential backoff

Avoid Rate Limit Trouble

• Don’t start a new sync on the same instance until the previous one is complete.
• Wait at least 6 hours between full syncs to avoid throttling.
• If you hit a 429 Too Many Requests, follow the retry-after header or queue the request.

Monitor Your Syncs Like a Pro

• Add your email to notificationEmails while creating the instance to get sync updates.
• Use the Sync Status API to check if a sync is running, failed, or finished.
• Keep logs of what you uploaded and which pages succeeded or failed.

Keep Your Data Clean and Connected

• Follow the right order: users → groups → group_users → activities.
• Always finish your sync. Data won’t show up in Zluri until the sync is completed properly.