This article contains details about troubleshooting Client API (FS.event, FS.setUserVars, and FS.identify) errors. For information and documentation about the Client API, review the FS.event, FS.setUserVars, and FS.identify documentation, and the Client API Requirements.
Table of Contents
- Too Big To Parse
- Invalid JSON
- Invalid Event Name
- Invalid Property Name
- Property Name Too Long
- Invalid Property Type
- Missing Property Type
- Invalid Value
- Value Too Big
- Expected Atom
- Invalid ID
- IDs Immutable
Client API Validation
The Client API allows users to capture custom data in FullStory via a Javascript API. FS.event, FS.setUserVars, and FS.identify each receive as arguments 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 FS.event and FS.setUserVars 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 for FS.event, FS.setUserVars, and FS.identify 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 FS.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: 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 type suffixes: _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, even if the type is inferred.
-
-
-
Description: There are 10 valid type suffixes: _bool, _date, _int, _real, _str, _bools, _dates, _ints, _reals, and _strs. If a property has a type suffix other than one of the ten listed suffixes (i.e. “_foo”), 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: This error means that the custom property name does not have a type suffix indicating the property type. The FS.event and FS.setUserVars docs specify 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: 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 FS.setUserVars/FS.identify properties have value length limits. The limits are as follows: “acctId” - 256 bytes, “uid” - 256 bytes, “email” - 128 bytes, “displayName” - 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 FS.setUserVars/FS.identify properties. If it is, trim the input to FS.setUserVars/FS.identify 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: 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 FS.setUserVars/FS.identify and will never be triggered by FS.event. FS.setUserVars/FS.identify 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 FS.identify. Check to make sure FS.identify can only be triggered after your application has received the unique identifier for the user.
-
-
-
Description: This error is only relevant to FS.setUserVars/FS.identify and will never be triggered by FS.event. FS.setUserVars/FS.identify have a reserved property “uid”, which can only be set once per session. If a call to FS.setUserVars/FS.identify 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. 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 FS.setUserVars, FS.identify, FS.event, etc., 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.