Error codes and handling - Bitrix24 JS SDK

Overview

The SDK raises errors through two related classes:

SdkError — thrown by SDK code itself (validation, configuration, deprecated paths, internal invariants). Always carries a code, a status (HTTP-like), and an optional originalError.
AjaxError extends SdkError — thrown when an HTTP call to Bitrix24 fails. Adds requestInfo (method, requestId, request params) so you can correlate with portal-side logs. Since v1.1.2 (#39), requestInfo does not include the full request URL and credential-bearing fields inside params are redacted — the goal is to keep webhook secrets out of toJSON() / toString() output.

Method-style results that don't throw — Call, CallList, Batch, BatchByChunk — surface failures through Result/AjaxResult: check .isSuccess and read .getErrorMessages(). FetchList, by contrast, does throw on failure (the generator can't complete partially).

import { SdkError, AjaxError } from '@bitrix24/b24jssdk'

try {
  // …SDK calls
}
catch (error) {
  if (error instanceof AjaxError) {
    // network / portal-side failure; error.code is the Bitrix24 code
    console.error(error.code, error.status, error.requestInfo?.method, error.requestInfo?.requestId)
  }
  else if (error instanceof SdkError) {
    // SDK-side issue; error.code starts with JSSDK_
    console.error(error.code, error.status)
  }
  else {
    throw error
  }
}

SdkError codes raised by the SDK

Codes are stable strings — match on them, don't parse messages.

Code	Status	Where it's thrown	What it means
`JSSDK_CORE_B24_NOT_INIT`	500	`AbstractB24` getters	You called a method on a `B24` instance whose constructor never finished. For `B24Frame`, await `initializeB24Frame()`; for `B24Hook`, the URL was malformed.
`JSSDK_CORE_B24_HTTP_V2_NOT_INIT`	500	`getHttpClient(ApiVersion.v2)`	The v2 HTTP client wasn't built (typically a configuration bug).
`JSSDK_CORE_B24_HTTP_V3_NOT_INIT`	500	`getHttpClient(ApiVersion.v3)`	Same, for v3.
`JSSDK_CORE_B24_API_WRONG`	500	`getHttpClient`	An unknown `ApiVersion` was requested.
`JSSDK_CORE_DEPRECATED_METHOD`	—	logger only	Not thrown — emitted as a `warning` log when you call deprecated `callMethod` / `callBatch` / `callListMethod` / `fetchListMethod` / `callBatchByChunk`. Migrate to `b24.actions.v2.` / `v3.`.
`JSSDK_CORE_METHOD_NOT_SUPPORT_IN_API_V3`	500	`AjaxResult.getNext()`	The deprecated `getNext()` paging helper does not work against a v3 client. `CallV3.make()` / `BatchV3.make()` no longer throw this — the SDK dropped its v3 method allowlist, so an unknown v3 method is reported by the server as `METHODNOTFOUNDEXCEPTION` (a soft error on the result).
`JSSDK_CORE_B24_FETCH_LIST_METHOD_API_V2`	500	`FetchListV2.make()` generator	An underlying page request failed; the generator stops. Catch around `for await`.
`JSSDK_CORE_B24_FETCH_LIST_METHOD_API_V3`	500	`FetchListV3.make()` generator	Same, for v3.
`JSSDK_CORE_B24_FETCH_TAIL_METHOD_API_V3`	500	`FetchTailV3.make()` generator	An underlying `tail` (keyset) page request failed; the generator stops. Catch around `for await`.
`JSSDK_CORE_B24_FETCH_TAIL_DESC_REQUIRES_INITIAL_VALUE` / `JSSDK_CORE_B24_CALL_TAIL_DESC_REQUIRES_INITIAL_VALUE`	500	`FetchTailV3.make()` / `CallTailV3.make()`	`order: 'DESC'` was requested without `initialValue`; the server pages by `field < value`, so the default `0` returns nothing. Pass `initialValue`.
`JSSDK_FILTER_V3_INVALID_FIELD` / `JSSDK_FILTER_V3_INVALID_OPERATOR` / `JSSDK_FILTER_V3_INVALID_IN` / `JSSDK_FILTER_V3_INVALID_BETWEEN` / `JSSDK_FILTER_V3_INVALID_NODE`	400	`FilterV3` builder	Client-side validation while building a v3 filter: empty field name, operator outside the 8 allowed, `in` value not a non-empty array, `between` with an undefined/null operand, or a malformed node passed to `build()` (e.g. a forgotten spread).
`JSSDK_BATCH_REF_V3_INVALID_PATH` / `JSSDK_BATCH_REF_V3_INVALID_REF_ARRAY`	400	`BatchRefV3` helper	Client-side validation of a v3 batch `$ref` / `$refArray` marker: empty/non-string path, or a `refArray` path without a dot (`alias.field`).
`JSSDK_AGGREGATE_V3_INVALID_FUNCTION` / `JSSDK_AGGREGATE_V3_INVALID_SELECT`	400	`AggregateV3` action	Client-side validation of a v3 `aggregate` select: a function outside `sum`/`avg`/`min`/`max`/`count`/`countDistinct`, or a select value that is neither a `string[]` nor a `{ field: alias }` map.
`JSSDK_BATCH_REF_V3_INVALID_PATH` / `JSSDK_BATCH_REF_V3_INVALID_REF_ARRAY`	400	`BatchRefV3` helper	Client-side validation while building a v3 batch `$ref`/`$refArray` marker: empty/non-string path, or a `refArray` path without a dot (`alias.field`).
`JSSDK_BATCH_TOO_LARGE`	400	v2 HTTP client	More than 50 commands handed to a single batch. Use `BatchByChunk`.
`JSSDK_BATCH_EMPTY`	400	v2 HTTP client	Empty `calls`.
`JSSDK_BATCH_SUB_ERROR`	500	batch processing	Wrapper for a sub-call failure inside a batch. Inspect the per-call result.
`JSSDK_INTERACTION_BATCH_BUILD_STRATEGY_V3_EMPTY_COMMAND`	400	v3 batch processing	A single command in a v3 batch was empty/malformed.
`JSSDK_INTERACTION_BATCH_BUILD_STRATEGY_V3_EMPTY_COMMANDS`	400	v3 batch processing	The whole `commands` array was empty.
`JSSDK_INTERACTION_BATCH_STRATEGY_V2_EMPTY_COMMANDS`	400	v2 batch processing	Same, for v2.
`JSSDK_INTERACTION_BATCH_STRATEGY_V2_EMPTY_COMMAND_RESPONSE`	500	v2 batch processing	A command in the response had no body — usually portal-side.
`JSSDK_INTERACTION_BATCH_EMPTY_PROCESSING_STRATEGY`	500	batch processing	Internal — strategy lookup failed.
`JSSDK_INTERACTION_BATCH_ROW_FAIL`	500	batch row parser	A single batch row could not be parsed.
`JSSDK_INVALID_PARAMS`	400	HTTP transport	The shape of `params` was rejected before the request was sent.
`JSSDK_PARAMS_TOO_LARGE`	413	HTTP transport	Serialized request body exceeded the size limit. Split the call.
`JSSDK_CALL_ALL_ATTEMPTS_EXHAUSTED`	500	HTTP transport	Degenerate config only (`maxRetries < 1`, no attempt made). On normal retry exhaustion the underlying error's real code is surfaced instead.
`JSSDK_UNKNOWN_ERROR`	500	various	Fallback when no more specific code applies.
`JSSDK_INTERNAL_ERROR`	500	`SdkError.fromException`	Default code when wrapping an unknown exception.
`JSSDK_INTERNAL_AJAX_ERROR`	500	`AjaxError.fromException`	Default code when wrapping an unknown HTTP error.
`JSSDK_CLIENT_SIDE_WARNING`	—	`B24Hook` constructor	Warning emitted when a `B24Hook` is instantiated in the browser — webhooks expose a portal-wide secret and shouldn't ship to client bundles.

REST-side codes that come back as `AjaxError`

Bitrix24 returns these in the error field of an HTTP response. The SDK lifts them into AjaxError.code verbatim — match on the string.

Code	HTTP status	Meaning	Typical fix
`expired_token`	401	OAuth access token expired.	The SDK refreshes the token and retries once on `B24Frame` / `B24OAuth`; `B24Hook` retries with the same credentials (its refresh is a no-op).
`invalid_token`	401	Token is malformed or revoked.	Handled like `expired_token` (auto-refresh + one retry); if the new token is still rejected the error surfaces — re-auth (OAuth) or fix the webhook URL.
`AUTHORIZE_ERROR`	403	Caller is not allowed to perform this action.	Wrong scope on the webhook/app, or the user lacks the access right (e.g. CRM permission).
`WRONG_AUTH_TYPE`	403	The token type doesn't match the endpoint (e.g. webhook used where OAuth is required).	Use the correct authentication method for the endpoint.
`QUERY_LIMIT_EXCEEDED`	503	Per-second / per-method rate limit hit.	Already handled by the built-in `RateLimiter` — increase `restrictionParams.maxConcurrent` only if you understand the cost.
`OVERLOAD_LIMIT`	503	Portal-wide load shedding.	Back off, retry after a few seconds. The SDK's `AdaptiveDelayer` already does this.
`ERROR_METHOD_NOT_FOUND`	400	Method name is wrong, or the app doesn't have the scope to see it.	Check spelling; check `app.info`'s `SCOPE` against the method's required scope.
`INVALID_REQUEST`	400	Bad parameters (missing required field, wrong type).	Inspect `error.message` — Bitrix24's description names the offending field.

This is not exhaustive — Bitrix24 publishes the full method-specific list at apidocs.bitrix24.com. Anything not listed here passes through as-is on AjaxError.code.

Handling patterns

Distinguish SDK bugs from portal-side failures

AjaxError extends SdkError, so order the instanceof checks specifically-first:

// @check-ignore: top-level try/catch with return, not valid at module scope

import { AjaxError, SdkError } from '@bitrix24/b24jssdk'

try {
  await $b24.actions.v2.call.make({ method: 'crm.deal.get', params: { id: 1 } })
}
catch (error) {
  if (error instanceof AjaxError) {
    // Portal-side: error.code is the Bitrix24 code (e.g. expired_token)
    if (error.code === 'expired_token') return refreshAndRetry()
    if (error.code === 'AUTHORIZE_ERROR') return showPermissionDenied()
    throw error
  }
  if (error instanceof SdkError) {
    // SDK-side: error.code starts with JSSDK_
    throw error // these are programmer errors, surface them
  }
  throw error
}

// @check-ignore: top-level try/catch with return, not valid at module scope

import { AjaxError, SdkError } from '@bitrix24/b24jssdk'

try {
  await $b24.actions.v3.call.make({ method: 'tasks.task.get', params: { id: 1 } })
}
catch (error) {
  if (error instanceof AjaxError) {
    // Portal-side: error.code is the Bitrix24 code (e.g. expired_token)
    if (error.code === 'expired_token') return refreshAndRetry()
    if (error.code === 'AUTHORIZE_ERROR') return showPermissionDenied()
    throw error
  }
  if (error instanceof SdkError) {
    // SDK-side: error.code starts with JSSDK_
    throw error // these are programmer errors, surface them
  }
  throw error
}

Use `isSuccess` for non-throwing methods

Call, CallList, Batch, BatchByChunk return a Result / AjaxResult instead of throwing:

// @check-ignore: top-level return in callList error-handling illustration

const response = await $b24.actions.v2.callList.make({ /* … */ })
if (!response.isSuccess) {
  console.error(response.getErrorMessages().join('; '))
  return
}
const items = response.getData()

// @check-ignore: top-level return in callList error-handling illustration

const response = await $b24.actions.v3.callList.make({ /* … */ })
if (!response.isSuccess) {
  console.error(response.getErrorMessages().join('; '))
  return
}
const items = response.getData()

For batches with isHaltOnError: false, isSuccess flips false on any sub-call failure but getData() still contains the successful entries. Iterate and check per-row .isSuccess if you need to know which calls passed.

Catch around `for await` for `FetchList`

// @check-ignore: top-level for-await in fetchList error-handling illustration

try {
  for await (const chunk of $b24.actions.v2.fetchList.make({ /* … */ })) {
    await persist(chunk)
  }
}
catch (error) {
  if (
    error instanceof SdkError
    && error.code === 'JSSDK_CORE_B24_FETCH_LIST_METHOD_API_V2'
  ) {
    // a page request failed; persisted chunks before this point are still good
    return resumeFromLastSavedId()
  }
  throw error
}

// @check-ignore: top-level for-await in fetchList error-handling illustration

try {
  for await (const chunk of $b24.actions.v3.fetchList.make({ /* … */ })) {
    await persist(chunk)
  }
}
catch (error) {
  if (
    error instanceof SdkError
    && error.code === 'JSSDK_CORE_B24_FETCH_LIST_METHOD_API_V3'
  ) {
    // a page request failed; persisted chunks before this point are still good
    return resumeFromLastSavedId()
  }
  throw error
}

Decide what to retry

Error condition	Safe to retry?
`QUERY_LIMIT_EXCEEDED`, `OVERLOAD_LIMIT`	Yes — the built-in limiter already does.
`expired_token`, `invalid_token` (401)	Yes — the SDK auto-refreshes the token and retries once on every entry point.
`AUTHORIZE_ERROR`, `WRONG_AUTH_TYPE` (403)	No — needs human intervention (re-auth, fix scopes).
`ERROR_METHOD_NOT_FOUND`, `INVALID_REQUEST`	No — request is malformed; retrying gives the same error.
Network / 5xx without a specific code	Yes — the limiter retries up to `maxRetries`; on final failure the underlying error (its real code) is surfaced. Bump `restrictionParams.maxRetries` if you need more attempts.