Troubleshooting

401 Unauthorized – The API key is invalid

This error occurs when the API key used in the request is missing, incorrect, or expired.

Fix:

• Ensure the API key is copied exactly from the Zluri Console.
• Include it in the api-key request header.
• Confirm the request is made over HTTPS.
• Regenerate the key if it may have been revoked or expired.

400 Bad Request – Invalid instance creation

This error occurs when the instance creation payload is malformed.

Fix:

• Ensure the appId matches your registered app in Zluri.
• Use a unique instanceName within your organization.
• Make sure all notification emails belong to valid Zluri users.

409 Conflict – Sync already running

This error means an active sync session is still ongoing.

Fix:

• Use the Get Sync Details API to check the current sync status.
• Abort the sync if it's stuck or unnecessary.
• Only one active sync is allowed per instance.

422 Unprocessable Entity – Schema validation failed

This occurs when uploaded data doesn’t match the expected schema.

Fix:

• Review the error response for problematic fields.
• Use the Get Entity Schema API to verify correct field types and formats.
• Use ISO 8601 format for timestamps.
• Retry upload with corrected data (same page number).

403 Forbidden – Cannot finish incomplete sync

This error happens when trying to complete a sync before all data is uploaded.

Fix:

• Ensure all required snapshot and incremental data is uploaded.
• Retry any failed uploads before finishing.
• Call the Finish Sync endpoint only after successful uploads.

422 Validation Error – Cross-entity validation failed

This indicates dependencies between entities are missing or broken.

Fix:

• Upload entities in logical order:
  • group_users after users and groups
  • user_activity after users
• Ensure referenced objects exist and are valid.

408 Timeout / Delayed Processing

This occurs when large syncs take longer to process.

Fix:

• Normal syncs complete within 2 hours; large syncs may take up to 4.
• Monitor progress using email notifications or the Get Sync Details API.
• Contact Zluri Support if a sync stays in started state for more than 4 hours.

200 OK – Data not visible in Zluri dashboard

The sync succeeded, but the data doesn’t appear.

Fix:

• Confirm the sync status is finished.
• Check for validation errors in sync details.
• Verify the data was processed and not filtered.
• Double-check dashboard filters and time range.

Getting Support

When contacting Zluri support, always include:

• Request ID: The x-request-id header from the problematic API response
• Instance Details: Sync ID
• Error Information: Complete error response and HTTP status code
• Timeline: When the error occurred and frequency
• Sample Data: Sanitized example of the data causing issues

Support Channels

Email: [email protected]
Include "SDK API Error" in the subject line Attach relevant logs and error responses