Frequently asked questions

Find answers to common questions about Instant synchronization on iOS.

Sync errors

Why am I seeing 502 Bad Gateway errors in my logs during syncing?

You may see error messages like this in your logs:

Failed syncing layer '...' of document '...': InstantError 5: HTTP error: 502

These 502 Bad Gateway errors are caused by keepalive timeout mismatches between your load balancer or reverse proxy and the upstream server. They occur when the proxy closes an idle connection that the upstream server was still expecting to use.

While the Instant client handles these errors gracefully and retries automatically, you should fix the underlying configuration to eliminate unnecessary reconnection overhead.

How to fix

Ensure your upstream server’s keepalive timeout is shorter than your load balancer’s idle timeout.

For example, if your load balancer has a 60-second idle timeout, configure your backend server to close idle connections after approximately 55 seconds. This way, the backend proactively closes idle connections before the load balancer times them out.

Refer to the documentation for your specific load balancer and backend server to configure these values.

Should I show sync errors to users?

We recommend not showing transient sync errors (like network connectivity issues) directly to users. The Instant SDK handles retries automatically using an exponential backoff strategy.

If you do present synchronization errors as alerts, consider filtering out (error code 16) for network connectivity issues. Users expect apps to sync data automatically when a connection is available, so these temporary errors rarely require user intervention.

Note that 502 errors indicate a server configuration issue that should be fixed rather than filtered — see the question above for how to resolve them.

How does Instant handle network errors?

When network errors occur, Instant automatically retries the sync operation using an exponential, jittered, backoff strategy. This means:

  1. The SDK waits a short time before retrying.
  2. Each subsequent retry waits longer (exponential backoff).
  3. A random “jitter” is added to prevent all clients from retrying simultaneously.

This approach ensures reliable synchronization without overwhelming the server during temporary outages.