Skip to main content
Version: v3

Error handling

This guide expands on how to manage errors thrown during the import of the data by a user.

Registering a callback

You can register a callback for handling any error thrown during the import of the data by a user. This callback could be called with a FlatfileError (a Flatfile custom Error).

onError: ({ error }) => {
// A FlatfileError contains additional error info.
console.log(`[${error.code}] ${error.userMessage}`);

Note: If onError is not provided, Flatfile SDK will automatically display userMessage to the user.


debugThe JWT was not signed with a recognized private key or you did not provide the necessary information to identify the end user
userMessageThere was an issue establishing a secure import session.

Error codes:

  • FF-UA-00 - token is missing or is signed with invalid private key.
  • FF-UA-01 - The embed ID was not provided as a value for the embed property in JWT.
  • FF-UA-02 - The embed ID provided as a value for the embed property is invalid. Make sure it contains a valid UUID.
  • FF-UA-03 - The embed does not exist.
  • FF-UA-04 - The embed does not have an active private key. Please reset your private key using Flatfile Dashboard.
  • FF-UA-05 - Your request was in developer mode, but used a known production embed ID. Please make sure you implement "Securing Data" part before using production embed. (See how to authenticate users in production)


debugInternal Server Error: "API error description"
userMessageA network request failed to complete. Please try again.

Common causes:

  • The user's internet connection is unstable or offline
  • Flatfile is experiencing internal system issues (See


debugembedId, token or onAuth property is required to initialize Flatfile.
userMessageThere was a configuration error preventing the data importer from loading.

Common causes:

  • embedId, token or onAuth property is missing in the config.


debugSomething went wrong while submitting your data.
userMessageChunk processing callback (onData) is calling next() after the timeout limit. Increase the timeout limit or reduce chunkSize.

Common causes:

  • onData receives two arguments (chunk and next) and next() callback has to be called within the acceptable chunkTimeout (30 seconds by default) (See Options)


userMessageAn unknown issue has occurred

Common causes:

  • Flatfile was unable to process the request