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).

Flatfile.requestDataFromUser({
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.

UnauthorizedError

PropertyValue
codeFF-UA-XX
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)

RequestError

PropertyValue
codeFF-RE-00
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 https://status.flatfile.io)

ImplementationError

PropertyValue
codeFF-IE-00
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.

ChunkTimeoutExpiredError

PropertyValue
codeFF-CT-01
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)

FlatfileError

PropertyValue
codeFF-GE-00
debug''
userMessageAn unknown issue has occurred

Common causes:

  • Flatfile was unable to process the request