This article contains details about troubleshooting Client API errors. For information and documentation about the Client API, review the Custom Event, Custom User Properties, and Set Identity documentation, as well as the Client API Requirements.
- Client API Validation
- API Error Kinds
- Rate Limiting and Cardinality Limiting
- Client and iframe Support
Client API Validation
The Client API allows users to capture custom data in Fullstory via a JavaScript API. Events, user properties, and identify APIs each receive a JSON object containing the custom data. The contents of these JSON objects are validated before they are captured in Fullstory. If the contents of a JSON object fail the validation step, they will not be captured and will not be searchable within Fullstory.
Fullstory makes it easy to identify these errors so you can be certain you’re seeing the complete picture of your data. To see if any validation errors have been triggered for your site, navigate to Settings > Integrations > API Errors.
This shows any validation errors for events and user properties APIs that have occurred on your site in the past 24 hours. If the table is empty, you’re error free! If not, keep reading for a more detailed guide on how to address these errors.
The first row of the API Errors table identifies the kind of error that caused the event or property to fail the validation step. The other rows identify the event or property that caused the error, and the frequency of the error.
The remainder of this article identifies each kind of error and provides suggestions how to fix the error.
API Error Kinds
Description: The total payload size cap is 512KB. If the payload is larger than 512KB, the entire payload will be rejected.
Solutions: Ensure you are only capturing relevant data with these API methods. For instance, it is almost never necessary to include an entire HTTP request response as an event payload. Instead, focus on properties that you need to search and filter data in Fullstory.
Description: The custom variable parser relies on the payload being a valid JSON object. If they payload contains is an invalid JSON object, the server will reject the payload.
Solutions: Verify that the submitted payload is a valid JSON object. https://www.json.org/ provides detailed documentation for the JSON format.
Description: Custom event names must be strings no longer than 250 characters. The empty string (i.e., “”) is also an invalid event name.
Solutions: Ensure that the event name meets the naming requirements. Trim long event names to 250 characters or shorter.
Description: For the Fullstory API V1 only, custom properties must be named using the pattern `ident_type`, where `ident` is a sequence of alphanumeric characters A-Z, a-z, or 0-9 and `type` is a short suffix that denotes the type of the property. There are 10 valid types: bool, date, int, real, str, bools, dates, ints, reals, and strs. Custom property names must start with an alphabetic character (A-Z or a-z). If any of these requirements are not met, the property will be rejected with this error. Learn more about custom property name requirements here.
Solutions: Compare the property name in the error table to the name requirements listed above. This error is most often triggered when the property name does not start with an alphabetic character.
Description: Custom properties have a maximum length of 512 characters including the type suffix. For nested custom events, the property name includes the dotted concatenation of all its parent properties. If a property name exceeds this length, it will be rejected.
Solutions: Use short property names where possible. Remember that the length requirements includes nested parent properties and type suffixes (for version 1).
Description: For the Fullstory API V1 only, there are 10 valid types: bool, date, int, real, str, bools, dates, ints, reals, and strs. If a property has a type other than one of the ten listed, this error will be triggered.
Solutions: Verify the erroring property is properly type suffixed. Check the suffix against the list of valid suffixes. Learn more about custom property name requirements here.
Description: For the Fullstory API V1, this error means that the custom property name does not have a type indicating the property type. The event and user properties APIs support 10 valid type suffixes: bool, date, int, real, str, bools, dates, ints, reals, and strs. If no type suffix is provided, we try to infer the type of the property prior to validation. This error only occurs when the type cannot be inferred and no type suffix is provided. Learn more about custom property name requirements here.
Solutions: For the Fullstory API V1, we recommend providing type suffixes for all custom properties instead of relying on type inferencing. This ensures all custom data is properly stored and searchable within Fullstory. This error will not occur if type suffixes are provided for all properties.
Description: If a payload contains a value that can’t be parsed into the suffixed type, this error will be triggered.
Solutions: This error occurs most frequently with dates. The server expects dates to be sent in ISO 8601Z format. If the date is passed in any other format, it will be rejected. Verify that custom properties are properly type suffixed for the type of data being sent to Fullstory.
Description: Five reserved properties have value length limits. The limits are as follows: “uid” - 256 bytes, “email” - 128 bytes, “displayName” - 256 bytes, “acctId” - 256 bytes, and “website” - 1024 bytes. For all other properties (including custom event properties), there is a global maximum length of 8192 bytes.
Solutions: Check if the property which is generating this error is one of the reserved user properties. If it is, trim the input to user properties so it does not exceed the length cap for that reserved property. If it is not a reserved property, trim the property so it does not exceed the maximum length cap.
Description: For the Fullstory API V1, properties that are type suffixed with a singular type (bool, date, int, real, and str) expect a single value. If they receive a list (i.e. [1, 7, 120]), this error will be thrown. Learn more about custom property name requirements here.
Solutions: Verify the erroring property is properly type suffixed. If the property receives multiple values, ensure that it is suffixed with a multiple value type.
Description: This error is only relevant to user properties API and will never be triggered by event API. The user properties API has a reserved property “uid”, which has specific requirements. The “uid” property cannot be set to any of the following values: 0, 1, -1, "nan", "n/a", "undefined", "null", and "nil". If it is, this error will be triggered.
Solutions: This error generally occurs when there is a race condition between your authentication flow and the call to identify. Check to make sure that the identify API is called after your application has received the unique identifier for the user.
Description: This error is only relevant to the user properties API and will never be triggered by events. The user properties API has a reserved property “uid”, which can only be set once per session. If a call to user properties attempts to set the “uid” property after it has already been set in the session, the client will try to split the session in two. If the session fails to split, this error will be thrown on the server.
Solutions: This error should never occur unless the payload is being manually manipulated by a user. If you see this error reported for your organization, please contact Fullstory Support.
Rate Limiting and Cardinality Limiting
Session-specific rate limits and organization-wide cardinality limits are specified in Client API Requirements. If the rate limit is exceeded for a given session, additional Client API calls will be ignored for the duration of the specified time limit. However, once this time period passes, we will continue to index and capture those events.. If the cardinality limit is exceeded for a given account, new property names will be ignored for that org.
Note: In some instances, passing in custom events that were set up in a different tool (such as Segment) may cause the account to exceed its cardinality limit for events and/or event properties. If this happens and you need guidance on how to approach limiting events or event properties on your account, contact us and we can help.
Client and iframe Support
While Fullstory provides support for data capture within an iframe, the client API is not currently supported within iframes. This means that calls to certain Fullstory APIs, will not be processed if they are called from within an iframe.
Developers can potentially work around this limitation by using the postMessageAPI, and passing events to the parent frame.