{
"code": 1200,
"message": "Template cannot be saved."
"detail": "Type mismatch: scope is undefined"
}
1001
Oops! There was an unexpected error. Please try again later.
1100
The template is malformed and cannot be loaded. Check it and try again.
1200
The template cannot be saved.
As Beefree SDK is improved and updated over time, the JSON structure we use to describe a document may change.
The endpoint bump.getbee.io validates and – when needed – updates a JSON document that had been created with an earlier version of the builder.
This guarantees backward compatibility for older documents: any document (e.g., an email campaign, a template in your email template catalog, etc.) using a JSON structure that the system finds to be out-of-date gets updated automatically the next time it is passed to the builder.
Currently, this feature is working in test mode, tracking any issue with existing JSON documents and allowing us to improve this service. During this testing phase, the system does not stop the loading of the builder when an issue is found.
To read the full list of possible errors, please refer to .
{"code":2200,"message":"required key not provided @ data[u'page'][u'body'][u'content'][u'style'][u'color']","error":"BAD REQUEST"}
Use this guide to implement and manage error handling for Beefree SDK in your application. You'll learn how to structure errors, classify them consistently, localize messages, and surface them effectively in your UI.
There are two primary error types:
Errors: These are critical and interrupt normal execution. They typically require the end user or system to take corrective action.
Warnings: These are non-blocking and indicate a recoverable or informational condition, like a locked module or a timed-out iframe.
Each error or warning may include the following:
code
Integer
A unique numeric identifier for the error or warning.
name
String
A short identifier for internal reference and debugging.
message
String
A human-readable message summarizing the problem.
detail
Object
Additional structured information, such as invalid parameters or language.
title
String
Optional. A localized title (from useIntl and errorsTranslations).
description
String
Optional. A localized description (from useIntl and errorsTranslations).
A categorized directory of all known error codes, their default messages, and classifications.
9900
apiGeneric
(unlisted fallback)
9999
genericError
An error occurred
503
fspGeneric
An error occurred
4001
authHeaderMissing
—
4005
authBearerInvalid
—
4010
authTokenExpired
—
5001
contentTypeFormUrlError
—
5002
unableToAuthenticate
—
5003
applicationDisabled
—
5005
invalidUID
—
5101
reLoginNeeded
Must login again and inject new token
5102
reLoginAndUpgradeNeeded
Must login again and re-create Plugin
1810
iframeTimeout
The iframe took too long to load
Warning
1820
iframeAuthFailed
Error authenticating the add-on
Warning
1100
invalid
The template is malformed and cannot be loaded. Check it and try again.
1101
invalid
The template cannot have more than one row when editSingleRow is true.
1300
invalid
The language is not valid (conflicts with LOCKED_ROW warning)
1300
locked
This row is locked and therefore its content cannot be edited.
Warning
1310
locked
Locked content blocks cannot be edited.
Warning
7020
lockedEntity
Locked entity
Warning
7005
invalidCommand
Invalid command
7010
invalidCommandOptions
Invalid command options
7030
entityNotFound
Entity not found
7040
elementNotFound
Element not found
7050
forbiddenCommand
The command execution is not allowed
1704
featureNotAvailable
This feature is not available for this plan
1705
featureNotEnabled
—
1706
featureNotAvailableInCoedit
—
1710
featureLimitReachedForPlan
—
1702
workspaceNotAvailableForPlan
—
1002
workspaceNotAvailable
—
3100
fspBeGenericError
3200
fspResourceNotFound
3300
fspPermissionDenied
3400
fspResourceAlreadyPresent
3401
fspResourceAlreadyPresentNoDialog
3450
fspFileNotUploaded
3500
fspRequestError
3600
fspUserError
3650
fspWrongCredentials
3750
fspInvalidImportUrl
6050
translationGenericBeError
6150
autoTranslateNotSupported
4101–4192
Various (e.g., CSS, HTML tags)
Specific JSON validation failures
4501–4504
CSS Conversion Errors
Reference the following pages for more information on additional errors:
onWarning CallbackThe onWarning callback returns information about a soft error that doesn’t impact the normal usage of the builder. You can use this callback to track these errors, display a message or change any behavior in your application. The callback manages JSON as the output data format.
To handle these warnings, add the onWarning callback to :
onError callbackThe onError callback returns information about the application errors. You can use this callback to track these errors, display a message or change any behavior in your application. The callback manages JSON as the output data format.
To handle these errors, add the onError callback to :
The extendedOnError feedback in Beefree SDK includes API-related failures, giving you additional insights and more control over error handling. With this optional extension, you can improve debugging, frontend error handling, and track issues more effectively.
You can extend onError to report API-related errors.
Take the following steps to extend onError:
Add the to your beeConfig.
Configure your callback function.
Add extendedOnError to your beeConfig file.
Set the boolean extendedOnError boolean to true.
The following code snippet provides an example of how this looks in the beeConfig:
This section lists and describes the possible error code and their corresponding codes, messages, and fixes.
Sample Error Message
onInfo CallbackThe onInfo callback is specifically designed for the and provides real-time usage data with each response, without storing or tracking the information. It also notifies your application when a user clicks on Apply for any AI-generated text suggestion.
To configure this in your app, add the onInfo callback to your :
Here’s an example of the data you can expect when the user asks to generate content:
Here’s an example of the data you can expect when the user applies AI-generated content:
{"code":2200,"message":"required key not provided @ data[u'page'][u'body'][u'content'][u'style'][u'color']","error":"BAD REQUEST"}
2000
Generic Bump Error
BAD REQUEST
400
Default generic bump error
2100
Invalid Target Version
BAD REQUEST
400
The target version does not exists
2200
[validation error detail]
BAD REQUEST
400
The JSON didn’t pass the validation.
The cause may be:
Missing keys
Added unknown keys
Message e.g.: required key not provided @ data[u'page'][u'body'][u'content'][u'style'][u'color']
2300
Missing Template Version
BAD REQUEST
400
There is no template version in the page
2400
Invalid Template Version
BAD REQUEST
400
The specified version is unknown
2500
Transformation Error
BAD REQUEST
400
Issues during JSON version migration
2600
Backward Transformation Error
BAD REQUEST
400
Issues during JSON version migration
3000
Service Error
SERVICE FAILURE
503
System failure not related with invalid json files
onWarning: function(errorMessage) { /* Implements function to handle warning responses */ }
{
"code": alfanumeric,
"message": string
}
{
"code": 1000,
"message": "Cannot call "send" while template is still loading."
}
1000
bee.save is unavailable
Cannot call bee.save() while template is still loading. Use the onLoad callback to determine when it’s safe to use the save method.
After onLoad(), if bee.save() is not accessible, it’s due to an expired token.
1610
Unknown module name
[Grouping Content tiles]Unknown module name.
1620
Duplicate module
[Grouping Content tiles]Duplicate module
1630
Invalid modulesGroups configuration
[Grouping Content tiles]Invalid modulesGroups configuration
1701
AMP content detected
The template loaded in the builder contains AMP content, but the builder is not configured with an AMP-compatible workspace. You can react to this warning by loading a workspace, using the loadWorkspace(type) method.
Message: AMP content has been loaded
1702
Workspace not available in current plan
The workspace you have configured for the builder is not available for your subscription plan.
Message: Workspaces not available in [${payload}] plan
1703
Action not available when loading template
The action you’re trying to perform on the builder instance is not available during the loading of a template.
Message: Cannot execute ${payload} during the template Loading
1704
Feature not available in current plan
The feature you have configured for the builder is not available for your subscription plan.
Message: [${featureName}] feature is not available in [${plan}] plan
1730
Content defaults for the Table module is not valid
Your content defaults are not valid for the table module.
2000
Generic Bump Error
[Template validation] Default generic bump error
2050
Generic Bump Error with warnings
[Template validation] Generic bump error, with warnings.
Note: This error is dynamic. Depending on the scenario, you will receive a different error message.
Use case: When the Bumper returns 200, but there are some portions of the JSON that should be corrected (for example unrecognized fields). The SDK triggers the onWarning, passing to the host-application an additional "warnings" array, containing the warning messages.
2100
Invalid Target Version
[Template validation] The target version does not exists
2200
[validation error detail]
[Template validation] The JSON didn’t pass the validation. The cause may be:
Missing keys
Added unknown keys
Message e.g.: required key not provided @ data[u'page'][u'body'][u'content'][u'style'][u'color']
2250
Bump template validation error
page/rows/0/columns/0/modules/0/descriptor/table/rows: malformed field (each row must contain the same number of cells)
2300
Missing Template Version
[Template validation] There is no template version in the page
2400
Invalid Template Version
[Template validation] There is no template version in the page
2500
Transformation Error
[Template validation] Issues during JSON version migration
2600
Backward Transformation Error
[Template validation] Issues during JSON version migration
3000
Service Error
[Template validation] System failure not related with invalid json files
onError: function(errorMessage) { /* Implements function to handle error messages */ } // [optional]
{
"code": alfanumeric,
"message": string,
"detail": string
}
{
"code": 1200,
"message": "Template cannot be saved."
"detail": "Type mismatch: scope is undefined"
}
const beeConfig = {
...
extendedOnError: true // [optional, default/fallback: false]
...
}; API_GENERIC_ERROR
9900
A generic network error occurred.
A network error occurred while calling service TEST https://beefree.io/test-url
{
code: 9900,
message: 'A generic network error occurred.',
detail: 'A network error occurred while calling service TEST https://beefree.io/test-url',
data: {
// an extract of Axios HTTP error details
"message":"Request failed with status code 404",
"status":404,
"code":"ERR_BAD_REQUEST",
"url":"https://beefree.io/test-url",
"method":"get",
"headers":{"Accept":"application/json, text/plain, */*"}
},
}onInfo: function (information) {
/* Implement function to handle info events such as when AI-generated text is applied */
}{
code: number,
message: string,
detail: object,
}
AddOn Information
{
"code": 1000,
"message": "Token usage for addon handle: ai-integration",
"detail": {
"handle": "ai-integration",
"promptId": "60bcc837-674c-4226-adad-91ee2a603b57",
"usage": {
"prompt_tokens": 50,
"completion_tokens": 100,
"total_tokens": 150,
"uid": "string"
},
},
}
{
"code": 1001,
"message": "Prompt '60bcc837-674c-4226-adad-91ee2a603b57' has been applied",
"detail": {
"handle": "ai-integration",
"promptId": "60bcc837-674c-4226-adad-91ee2a603b57",
"moduleId": "9c2c6e63-f9c3-4e8d-9e3e-f9a658fefe46",
"content": "Discover the Best Email Editor"
}
}You can return custom errors from your application that will be displayed in the file manager.
To do that we reserved codes from 3900 to 3999. An error sent with an error code number in this range displays the message as the error title and the details as the error text.
Your file storage doesn’t support file names with the character “?”
The front end doesn’t stop the upload, as this character is allowed by other APIs and storages
When your API gets the file, returns the following error: Code: 39105 HTTP Status: 400 Message: Upload error Details: The file name is not allowed. Please make sure it does not contain one or more of these characters: \ / < > ? |
The file manager inside the editor displays:
{"code":3200,"message":"Resource Not Found","details":"http:\/\/myfsp.com\/docs\/errorcodes\/404"}
3001
FSP Error
503 Service Unavailable
Default generic FSP Error
3100
Something went wrong accessing backend filesystem
503 Service Unavailable
Default generic Error
3200
Resource not found
404 Not Found
File or directory not found
3300
Permission denied
403 Forbidden
Permission denied to access a file or a directory
3400
Resource Already Exists
409 Conflict
File or directory already exists
3450
File Not Uploaded
422 Unprocessable Entity
Error during file upload
3500
Request Error
400 Bad Request
Server could not understand the request due to invalid syntax
3600
User Error
403 Forbidden
Not a valid S3 custom storage
3650
Wrong Username or Password
401 Unauthorized
Wrong user credentials
from 3900 to 3999
Custom error message
Custom HTTP status code
{"code":4001,"message":"Authentication error","details":"Authentication header is missing"}
4001
Authentication error
401 Unauthorized
Authentication header is missing
4005
Authentication error
401 Unauthorized
Bearer token format is invalid
4010
Authentication error
401 Unauthorized
Token expired
5101
Expired token is no longer refreshable
You need to create a new login. With the new token you can update the token in the current Builder instance or create a new Builder instance using the new token and the current JSON template present in this event.
5102
The token can't be updated in this builder instance
Create a new login and a new Builder instance using the new token and the current JSON template from this event.
4015
Bump service error
400 Bad Request
Error while calling Bump service
...1
Bump service error
400 Bad Request
…1
1: In case of a Bump error, the JSON parser forwards to the user the error code it receives from the Bump.
4101
JSON pre-processing failed
400 Bad Request
Generic parsing error
4102
JSON pre-processing failed
400 Bad Request
Error managing default CSS rules related to the row container styling
4103
JSON pre-processing failed
400 Bad Request
Error managing default CSS rules related to the row content styling
4104
JSON pre-processing failed
400 Bad Request
Error merging CSS rules related to the row container and content styling
4105
JSON pre-processing failed
400 Bad Request
Error while checking special <code> tags
4110
JSON pre-processing failed
400 Bad Request
Error while checking for HTML blocks
4115
JSON pre-processing failed
400 Bad Request
Error while checking conditional statements
4120
JSON pre-processing failed
400 Bad Request
Error while adding conditional statements to rows
4125
JSON pre-processing failed
400 Bad Request
Error while adding styles to rows container
4130
JSON pre-processing failed
400 Bad Request
Error while adding classes for conditional statements
4135
JSON pre-processing failed
400 Bad Request
Error while adding computed styles for each grid block row
4140
JSON pre-processing failed
400 Bad Request
Error while calculating cell widths
4145
JSON pre-processing failed
400 Bad Request
Error while adding background on columns
4190
JSON pre-processing failed
400 Bad Request
Error while adding main CSS styles
4191
JSON pre-processing failed
400 Bad Request
Error while adding main CSS media queries styles
4192
JSON pre-processing failed
400 Bad Request
Error while adding client-specific CSS styles
4501
Pre-processing error
403 Forbidden
Error assembling CSS Rules
4502
Pre-processing error
403 Forbidden
Error compiling general page CSS styles
4503
Pre-processing error
403 Forbidden
Error compiling body CSS styles
4504
Pre-processing error
403 Forbidden
Error converting JSON styles rules to CSS
4201
HTML creation error
400 Bad Request
Generic JSON to HTML conversion error
4202
HTML creation error
400 Bad Request
Communication error to JSON content workers
4210
HTML creation error
400 Bad Request
Communication error with text block worker
4211
HTML creation error
400 Bad Request
Text block worker has notified a processing Error: (…)1
4220
HTML creation error
400 Bad Request
Communication error with button block worker
4221
HTML creation error
400 Bad Request
Button block worker has notified a processing Error: (…)1
4230
HTML creation error
400 Bad Request
Communication error with video block worker
4231
HTML creation error
400 Bad Request
Video/MergeContent block worker has notified a processing Error: (…)1
4240
HTML creation error
400 Bad Request
Communication error with social block worker
4241
HTML creation error
400 Bad Request
Social block worker has notified a processing Error: (…)1
4242
HTML creation error
400 Bad Request
Communication error with icon block worker
4243
HTML creation error
400 Bad Request
Icon block worker has notified a processing Error: (…)1
4244
HTML creation error
400 Bad Request
Communication error with menu block worker
4245
HTML creation error
400 Bad Request
Menu block worker has notified a processing Error: (…)1
4250
HTML creation error
400 Bad Request
Communication error with image block worker
4251
HTML creation error
400 Bad Request
Image block worker has notified a processing Error: (…)1
4260
HTML creation error
400 Bad Request
Communication error with merge content worker
4270
HTML creation error
400 Bad Request
Error handling custom addon module
4601
Rendering error
403 Forbidden
Error cleaning up button module HTML code
4602
Rendering error
403 Forbidden
Error cleaning up text module HTML code
4603
Rendering error
403 Forbidden
Error checking form elements
4604
Form validation error
403 Forbidden
Error in (…)2
4605
Rendering error
403 Forbidden
Custom video format not supported
4920
Rendering error
403 Forbidden
Video block is corrupted
4600
Rendering error
403 Forbidden
(…)1
1: Additional details are provided, depending on the error that the content worker is reporting.
2: Additional details are provided, depending on the form field that missed validation.
4301
HTML post-processing error
400 Bad Request
Generic post-processing error
4310
HTML post-processing error
400 Bad Request
Error while transforming images URI
4320
HTML post-processing error
400 Bad Request
Error inserting custom HTML codes
4330
HTML post-processing error
400 Bad Request
Error replacing custom Beefree SDK code tags
4340
HTML post-processing error
400 Bad Request
Error inserting display conditions
4700
Post-processing error
403 Forbidden
Error assembling the final HTML page