Errors & Warnings

Error handling

When a call fails, its promise rejects with a ClientApiError carrying three properties:

• error — machine-readable error code.

• message — human-readable explanation.

• status — the HTTP status of the failed request.

try {
  await SL.client.recommendations.subscribe({ email, uuids });
} catch (error) {
  if (error.name === "ClientApiError") {
    console.error(error.error, error.message);
  }
}

The errors you're most likely to run into:

• bad_request (400) — a required argument is missing or invalid: a missing or malformed email, or a missing uuid or uuids.

• not_found (404) — the uuid you passed doesn't match any of your recommendations or offers.

• forbidden (403) — the Client API is not enabled for your publication, or the page's origin is not registered as an allowed origin. See Early Access to get it enabled or add a domain.

If the SparkLoop script itself fails to initialize, SL.client methods reject with a regular Error instead of a ClientApiError.

Subscribe and claim only with consent

Readers must explicitly choose the recommendations you subscribe them to and the offers you claim for them, without being misled in any way. Failure to comply results in a permanent block of your SparkLoop account.

Never cache recommendations or offers

Recommendations and offers are generated for a specific reader at a specific moment, and their availability changes continuously. If a recommendation or offer is no longer recommendable by the time your subscribe or claim call arrives, it is discarded: the call still succeeds, but nothing is registered and nothing is earned.

To stay safe:

• Never cache or store recommendations or offers — not even for a few hours.

• generate right before displaying, and subscribe/claim right after the reader acts.

• When spotlighting an individual recommendation or offer, fetch it right before displaying it and check its recommendable field.