Troubleshoot the Amperity Event Streams SDK

Use these steps when events from the Amperity Event Streams SDK do not arrive in a real-time event stream.

Check how the request fails

Open your browser’s developer tools, and then review the network requests to the collector URL. The response status shows what to fix.

Symptom	What to do
404 Not Found	Confirm the write key matches a key on the event stream settings page and was not deleted. A new write key can take up to a minute to become active, so wait and try again.
400 Bad Request	Confirm that the body is JSON with an events array of event objects.
413 Payload Too Large	Reduce the size of the properties you send. A request must be no larger than 1 MiB.
429 Too Many Requests or 503 Service Unavailable	Wait. The SDK sends the event again on its own, with longer waits between attempts. If you send events from your own code, send them again later.
The request is blocked by the browser	Check for a content security policy on your website. Allow connections to the collector URL in the connect-src directive.
No request is sent	Confirm amperity.load() runs before any other SDK call and that it did not reject. Confirm that the SDK is not waiting for a consent decision. See Consent.

Events are accepted but do not appear

If the collector returns 202 Accepted, check the status and downstream_status of each event in the response:

• 204 means the event stream is in Drop mode. The event is accepted and then discarded. Set the event stream mode to Process.

• 409, with the status rejected, means the event stream is in Reject mode and does not accept events.

• 202 means the event reached the event stream. Check that the stream’s mode is Process.

• Confirm that the event stream recognizes the events that the SDK sends, and that it has an event type for each event name. See How events are processed and Events are unrecognized, ignored, or invalid.

Find the reason an event failed

page(), track(), and identify() return a promise that resolves when the SDK queues the event. Delivery happens afterward, so check lastFailure() on the result after the request has had time to finish:

const result = await amperity.track('Order Completed', { order_id: '1001' });

// Later, after the request has had time to finish:
const failure = result?.lastFailure();
if (failure) {
  console.log(failure.reason, failure.message);
  if (failure.reason === 'http') console.log(failure.statusCode);
}

lastFailure() returns undefined until an attempt fails or the SDK drops the event. The reason is http for a response that was not successful, network for a connection failure, consent when consent was not granted, or overflow when the SDK dropped the event because too many events were waiting. Only an http failure has a statusCode. With the script tag, a call made before the SDK finishes loading returns undefined instead of a result.

Errors from SDK calls

amperity.load(), page(), track(), and identify() return a promise, which rejects with an error when the call fails. The other methods throw the error when you call them. With the script tag, an error from a call that ran before the SDK finished loading is written to the browser console. Each error has a name you can check:

• NotLoadedError: you called a method before amperity.load().

• ValidationError: an option or an argument is not valid. The error names it in its field. For example, amperity.load() rejects an empty writeKey or endpoint, a logLevel that is not one of the supported values, and a consent.provider other than custom.

• UnsupportedEnvironmentError: amperity.load() ran outside a browser, such as during server-side rendering.

To see the SDK’s warnings in the browser console, such as a second amperity.load() call or an event larger than 32 KiB, set the logLevel option to warn. The default is error.