JavaScript Limits And Errors

Use the JS SDK as if limits and errors are part of the type system.

Good integrations enforce payload bounds, map structured error codes directly, and never assume the runtime is broader than create, load, and sync.

SDK Surface

The SDK should expose typed statuses and typed errors, not force application code to inspect raw HTTP responses.

PersistlyPayloadTooLargeError for metadata/state values that exceed documented limits.

PersistlyUnauthorizedError when the runtime key is missing, invalid, or for the wrong environment.

PersistlyNotFoundError when the saveId does not exist in the keyed environment.

PersistlyRateLimitedError when the runtime asks the client to retry later.

PersistlyServerError when Persistly fails internally and the operation result is unknown.

Status And Errors

Use PersistlySyncStatus plus typed SDK errors in application code.

import {
  PersistlyClient,
  PersistlySyncStatus,
  PersistlyPayloadTooLargeError,
  PersistlyUnauthorizedError,
} from "@persistly/sdk-js";

const client = new PersistlyClient({
  runtimeKey: process.env.PERSISTLY_RUNTIME_KEY!,
});

try {
  const result = await client.syncSave(saveId, {
    baseVersion: local.version,
    metadata: local.metadata,
    state: nextState,
  });

  if (result.status === PersistlySyncStatus.Accepted) {
    local = result.save;
  }

  if (result.status === PersistlySyncStatus.Conflict) {
    local = result.save;
  }
} catch (error) {
  if (error instanceof PersistlyPayloadTooLargeError) {
    console.error(error.code, error.details);
  }

  if (error instanceof PersistlyUnauthorizedError) {
    console.error("Check the runtime key and target environment.");
  }
}

Common Mistakes

The fastest path to drift is ignoring these constraints.

Do not use externalUserId as a public runtime lookup key from shipped clients.

Do not treat runtime keys as privileged admin secrets.

Do not invent slot_id semantics at the platform layer; put save-selection labels in metadata instead.

Do not ignore canonical sync responses. Replace your local canonical snapshot after every create, load, or sync.

Do not sync every frame or use Persistly for real-time PvP state.