Error Codes
Bitrix24 reports an error with a JSON structure containing the error and error_description fields. The structure arrives in the response body instead of the data that the method would return on a successful call. This is how the response to a single call is built — in a batch request, subquery errors arrive differently, inside result:
{
"error": "ERROR_HANDLER_ALREADY_EXIST",
"error_description": "Handler already exists!"
}
The ERROR_HANDLER_ALREADY_EXIST code from the example was returned by a specific method — it is not part of the system error list.
This page covers the system codes — the ones the REST API returns in response to any method. The codes of a specific method and the codes of the authorization server are listed on other pages: the Where the Error Code Is Described section shows where to look for the code you need.
Choose a tool for developing with an AI agent:
- use Alaio Vibecode to build an app for Bitrix24 from a task description without knowing any programming language. The agent writes the code and deploys the app to a server, with no manual hosting setup
- use the MCP server to develop a REST API integration in your own project. The agent refers to the official REST documentation
Error Response Fields
|
Name |
Description |
|
error |
String error code. It consists of digits, Latin letters, and underscores. It may arrive empty — in that case only |
|
error_description |
Error message for the developer. Do not show it to the end user without processing |
How to Recognize an Error in the Response
Recognize an error by the set of fields in the response body, not by the HTTP status: subquery errors of a batch request arrive with status 200. The status serves another purpose — write it to the log together with the code, it helps when investigating an incident.
|
What the Response Body Contains |
What It Means |
What to Do |
|
The |
The call succeeded |
Parse the data from |
|
The |
The call failed |
Parse the error: if the code in |
|
The |
The batch request was accepted, but some of its subqueries failed |
Parse the subquery errors by command keys |
The result.result_error field is always present in a batch response: in a successful batch it arrives empty — "result_error": []. The sign of an error is the entries in this field, not the field itself. A batch request returns a subquery error under the same key the command was passed with in the request. How the batch response is built is covered on its page.
The error field may arrive empty — in that case only error_description shows the reason. Errors of a specific method arrive this way, most often parameter validation and object lookup errors. For example, a request for a deal with a non-existent identifier returns status 400 and the body {"error": "", "error_description": "Not found"}. Check the response for the presence of the error key, not for its value:
// build the url according to the rules from the "How a Request Is Executed" section,
// the method name is needed here only for the log
async function callMethod(method, url) {
const response = await fetch(url);
const data = await response.json();
// the call failed: check for the error key, not for its value
if ('error' in data) {
// the code goes into a separate field so that the calling code can branch on it,
// while the status and the method name are kept for the log
const error = new Error(data.error_description);
Object.assign(error, { code: data.error, status: response.status, method });
throw error;
}
// batch subquery errors are stored under the command keys
// in a successful batch the field arrives empty, so count the entries instead of checking for the field
const batchErrors = data.result?.result_error ?? {};
// whether to retry the subqueries or abort the scenario is up to the calling code
return {
result: data.result,
batchErrors,
hasBatchErrors: Object.keys(batchErrors).length > 0
};
}
You do not always have to parse the response manually: Bitrix24 SDKs take the field checks over and report the error by the means of the language. The form in which the error code arrives depends on the library — see the page of the SDK you use. An integration defines its reaction to a particular code itself, so the rules below apply to work through an SDK as well.
In the XML format, the same data arrives as the <error> and <error_description> elements inside <response>. How to choose the response format is described on the How a Request Is Executed page.
Where the Error Code Is Described
The list of codes depends on which part of Bitrix24 returned the error.
|
Error Source |
When It Occurs |
Where the Codes Are Described |
|
Bitrix24 REST API |
During the operation of the REST API itself: invalid authorization data, insufficient permissions, exceeded limits, REST API unavailable |
Statuses and System Error Codes on this page |
|
A specific method |
When the rules of the method itself are violated: invalid parameter format, missing object, unacceptable field value |
The "Error Handling" section on the method page — for example, the crm.item.add method lists there the codes specific to creating an SPA item |
|
The |
When exchanging the authorization code for tokens and when renewing them |
Method errors are described on the method page because they depend on the set of parameters and the state of the object.
Statuses and System Error Codes
HTTP Status: 4xx, 5xx
The errors described below are returned by the REST API itself, not by the logic of a specific method. They can arrive in response to any method.
|
Status |
Code |
Description |
|
|
|
An internal server error has occurred. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The server returned an unexpected response. Retry the call, and if the error persists, contact the server administrator or Bitrix24 technical support |
|
|
|
The request intensity limit has been exceeded |
|
|
|
The method is blocked because the request resource intensity limit has been exceeded. The block is lifted automatically once the accumulated execution time of the method no longer exceeds the limit |
|
|
|
The request contains no authorization data: neither an access token nor a webhook code was passed |
|
|
|
Methods are called over the HTTPS protocol only |
|
|
|
The REST API is blocked due to overload. This is a manual individual block. To have it lifted, contact Bitrix24 technical support |
|
|
|
REST API access is not active for this account. In Bitrix24 Cloud, check the current plan or trial status: Vibe+ plans include REST API access, while Essentials plans do not. A webhook receives a different error message — |
|
|
|
No active webhook with the specified user identifier and secret code was found |
|
|
|
No method with this name was found. The name is misspelled, the method does not exist in the REST API, or it is unavailable without the required scope |
|
|
|
The request requires broader permissions than the token has: for a webhook these are the permissions granted to it, for an application it is the scope. For an application, the error message ends with |
|
|
|
The access token has expired |
|
|
|
The application is installed, but the Bitrix24 administrator has granted access to it only to specific users |
|
|
|
The public part of the site is closed. To open it on an on-premise installation, disable the "Temporary closure of the public part of the site" option. Path to the setting: Desktop > Settings > Product Settings > Module Settings > Main Module > Temporary closure of the public part of the site |
How to Handle Errors in an Integration
Branch on the code from the error field, not on the text from error_description. The error text of a method arrives in the language of the Bitrix24 interface and may change, so it cannot serve as the basis for branching.
Reacting to System Codes
The row order matches the order in the table of system errors above, and the causes of the errors are described there.
|
Code |
What to Do |
|
|
Retry the call in a few seconds. If the error persists, contact the server administrator in the on-premise version or technical support |
|
|
Reduce the request intensity and retry the call later. The intensity allowed on each plan is listed in the REST API limits |
|
|
Pause the calls to this method. Use the |
|
|
Pass an access token or a webhook code in the request: the current request has neither |
|
|
Replace |
|
|
Do not retry the call, and contact technical support: the block is manual and will not be lifted on its own |
|
|
Switch to a commercial plan. With any other status, this code comes from a method — see the explanation after the table |
|
|
Check the user identifier and the webhook code in the request URL: no active webhook with that pair was found |
|
|
Check the spelling of the method name and the presence of the required scope |
|
|
Add the missing scope to the application or to the webhook |
|
|
Renew the tokens and retry the call |
|
|
Ask the Bitrix24 administrator to grant the user access to the application |
|
|
Open the public part of the site: while it is closed, the REST API will not respond |
The same code can appear both in the system list and in the list of a specific method — in that case the HTTP status tells them apart. System authorization and access errors arrive with status 401, method errors with 400 or 403. For example, ACCESS_DENIED with status 401 means that the REST API is not available on the current plan, while the same code with status 403 and the text Access denied! Application context required came from a method that requires an application context.
Retrying a call that returned a method error gives the same result — fix the request first.
Similar Codes Returned by Methods
Three more codes come from individual methods rather than from the REST API as a whole. The batch request returns ERROR_BATCH_METHOD_NOT_ALLOWED when a subquery cannot be executed in a batch, and ERROR_BATCH_LENGTH_EXCEEDED for every subquery beyond 50 — both are covered on its page. The configuration.import.register method returns ERROR_MANIFEST_IS_NOT_AVAILABLE when the request contains no manifest code or the import is not allowed for that manifest.
What to Write to the Log
Write error, error_description, the HTTP status, and the name of the called method to the integration log. Do not write authorization data — tokens and webhook codes — to the log: they give access to Bitrix24 data.