Behaviour changes inside 2.x

The other two guides on this page are about symbols that are removed. This one is about the smaller set of changes that removed nothing and still need something from you: a call that used to return now throws, or a value that used to be ignored now means something.

2.3.0 — a restApi:v3 batch sends a different request body

What changed. A v3 batch now puts its commands on the wire as a bare top-level JSON array. It used to send an object with numeric keys, and on an OAuth transport it added the access token as one more top-level entry:

before (B24Hook)   {"0":{…},"1":{…}}
before (B24OAuth)  {"0":{…},"1":{…},"auth":"<access token>"}
now                [{…},{…}]

On a server, B24OAuth sends the token in an Authorization: Bearer header instead of in the body.

What it fixes. A v3 batch from B24OAuth never worked at all. The portal reads every top-level entry of a batch body as a command and requires method and query on each, so the auth entry failed the whole batch with BITRIX_REST_V3_EXCEPTION_INVALIDSELECTEXCEPTION before a single command ran. A webhook survived only because PHP cannot tell a JSON list from a map with sequential integer keys.

The same rule had a second victim, invisible until the first was fixed: a command written without params — { method: 'rest.scope.list' }, or the tuple ['rest.scope.list'] — went out with no query key, because JSON.stringify drops an undefined value. That is refused under the same code, and one such entry takes the whole batch down with it. Commands now always carry a query, empty if there is nothing to put in it.

Who is affected.

• B24OAuth on a server — actions.v3.batch.make and actions.v3.batchByChunk.make start working. Any workaround that looped single calls can go.
• A browser — B24Frame, or B24OAuth used client-side — the same, with the credential in the query string rather than a header. See the note below.
• Anything that inspects the request — a reverse proxy, a WAF body rule, an egress gateway, a recorded HTTP fixture (nock / msw / VCR), or a test that asserts on the request body. The body is an array now for every transport, B24Hook included, even though a webhook batch already worked; and a server-side OAuth batch carries a header it did not carry before. Re-record fixtures, and let Authorization through the proxy.
• Log readers — the post/send line logs the body it sends, so a v3 batch now writes [{…},{…}] where it wrote {"0":{…},…,"auth":"***REDACTED***"}.

What to do. Nothing in your own code. The action arguments and the return shape are unchanged, and so is AjaxError.requestInfo.params — that has always carried the commands array, not the formatted body.

One thing to know if you sit behind a redirect. The header-carrying request is sent with maxRedirects: 0, so it will not follow a 301/302 while holding the token — follow-redirects keeps Authorization across a same-host or subdomain hop, and the credential in the body was never exposed that way because a redirect drops the body. Only that one request is constrained; see configuring the axios instance if you need to change it.

3.0.0 — every keyset walk now stops after 10 000 pages

What changed. callList / fetchList (both API versions) and callTail / fetchTail (v3) take a maxPages ceiling, and it defaults to 10 000. A walk that reaches it stops with JSSDK_ACTION_MAX_PAGES_EXCEEDED naming the method. The same walkers also take an AbortSignal as signal, and the eager ones take a progress callback.

What it replaces. An unbounded while (true). The stall guard added in 2.3.0 catches a cursor that stops moving, but not one that keeps moving and never ends — a filter that matched far more than intended, or a cursor cycling between two values, which never repeats the immediately preceding one.

Who is affected. Anyone whose walk legitimately reads more than 10 000 pages — 500 000 rows at the default page size of 50. That is past the point where the eager helpers, which hold every row in memory, are the right tool; but a streaming walk over a table that large used to complete and now stops.

What to do. Nothing, unless you read more than 10 000 pages. If you do, pass a higher maxPages. Note that reaching the ceiling does not throw away what was read: the eager walkers resolve with the rows they collected and the error attached, so the shape to check is isSuccess, not a catch.

import { B24Hook } from '@bitrix24/b24jssdk'

const b24 = B24Hook.fromWebhookUrl('https://your-portal.bitrix24.ru/rest/1/SECRET')

const response = await b24.actions.v2.callList.make({
  method: 'crm.item.list',
  params: { entityTypeId: 2 },
  idKey: 'id',
  customKeyForResult: 'items',
  maxPages: 40_000
})

if (!response.isSuccess) {
  // The rows are still here — they are correct, merely incomplete.
  console.warn(response.getErrorMessages(), response.getData().length)
}

A ceiling that is not a positive integer is refused at call time with JSSDK_ACTION_INVALID_MAX_PAGES rather than coerced.

2.3.0 — a stalled pagination cursor now throws

What changed. callList / fetchList (both API versions) and callTail / fetchTail (v3) now raise SdkError with code JSSDK_ACTION_CURSOR_STALLED when a full page comes back and the cursor read from it equals the one just sent. That means the server did not apply the page condition, so the same page will keep arriving.

What it replaces. Not an error — a hang. The walk had no way to end: the page is full, so no end-of-data check fires. fetchList / fetchTail yielded the same rows for ever; callList / callTail grew an array until the process ran out of memory.

Who is affected. Anyone whose idKey / cursorIdKey pair does not match the method. The measured case is restApi:v2 tasks.task.list with idKey: 'id' and no cursorIdKey: the response spells the id lowercase, the filter accepts it uppercase, so >id matches nothing and is dropped.

What to do. Fix the configuration — that is what the error text tells you — and, if you call the eager helpers, add a try/catch:

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

const b24 = B24Hook.fromWebhookUrl('https://your-portal.bitrix24.ru/rest/1/SECRET')

try {
  const response = await b24.actions.v2.callList.make({
    method: 'tasks.task.list',
    idKey: 'id', // the id as the response spells it
    cursorIdKey: 'ID', // the field the request sorts and filters by
    customKeyForResult: 'tasks'
  })
  console.log(response.getData())
} catch (error) {
  if (error instanceof SdkError && error.code === 'JSSDK_ACTION_CURSOR_STALLED') {
    // the walk was repeating one page — nothing collected is worth keeping
    console.error('pagination is broken for this method, check idKey/cursorIdKey')
  }
  else {
    throw error
  }
}

If you stream, the duplicates are already yours. fetchList / fetchTail yield each page as it arrives, so by the time this throws your consumer has already seen the repeated page. A catch that resumes from the last saved id is right for a failed page request and wrong here — roll the persisted chunks back instead.

One more shape. A cursorField naming an object- or array-valued field is now treated as no cursor at all: the walk logs a warning and stops, where before it paged for ever (two distinct references are never equal, so the guard alone would not have caught it). Point cursorField at a scalar.

2.3.0 — a v3 aggregate returns strings, and null over no rows

What changed. AggregateResultV3 was Record<string, number> and is now Partial<Record<AggregateFunctionV3, Partial<Record<string, string | number | null>>>>. The SDK does not convert the values.

before  { count: { id: 27 },    sum: { amount: 12345.67 } }   // what the type claimed
now     { count: { id: '27' },  sum: { amount: '12345.6700' } } // what a portal sends

Why. The contract had never been measured — no shipped module publishes an *.aggregate action on any of four portals — so it was verified against a module written for the purpose, reaching the same AggregateOrmActionTrait / OrmRepository::getAllWithAggregate() every future module will. Values arrive as strings, with the scale the database chose. Over a filter matching no rows, count is '0' and every other function is null, because SQL aggregates over an empty set are null and only count has a zero.

Who is affected. Anyone doing arithmetic straight off the result. data.count.id + 1 concatenates now instead of adding, and a ?? 0 written against a missing key does not catch an explicit null.

What to do. Convert deliberately, and pick the conversion per field:

import { Text } from '@bitrix24/b24jssdk'

const response = await $b24.actions.v3.aggregate.make({
  // @check-ignore: some.entity.aggregate is a placeholder — no shipped module publishes an *.aggregate action
  method: 'some.entity.aggregate',
  select: { count: ['id'], sum: ['amount'] }
})

if (response.isSuccess) {
  const data = response.getData()
  // A row count is safe through a float.
  const rows = Text.toNumber(data?.count?.id ?? 0)
  // A money total is not — `Text.toNumber` goes through `Number.parseFloat`,
  // so `'12345.6700'` loses precision exactly where a ledger cannot afford it.
  // Keep the string, or hand it to a decimal library.
  const total = data?.sum?.amount ?? null
}

One request shape is now refused before it is sent. A select naming no aggregate column at all — {}, { count: [] }, { count: {} } — throws SdkError with code JSSDK_AGGREGATE_V3_EMPTY_SELECT. The portal answers such a request with a bare 500 carrying nothing to act on, after the whole retry budget is spent on a call that was never going to work. An empty list beside a non-empty one is still sent, because the portal answers it.

See also

• Error codes and handling — the full table, including what each walker's remedy text names.
• Discovering entity fields — before an aggregate call works at all, the field has to be filterable, which is not the same as selectable.
• CHANGELOG — every change in the line, not only the ones that need action.