Limits, queues, and pauses

A detailed breakdown of the codes the Vibecode API returns when the request rate is throttled, the portal queue is full, or a method is paused on the Bitrix24 side.

The summary table of all Vibecode API codes — Error codes.

`RATE_LIMITED` (429)

One of the rate limits fired: the Vibecode platform edge, an endpoint's own limit, or a limit on the Bitrix24 side.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "QUERY_LIMIT_EXCEEDED",
    "hint": "Wait 1-2 seconds and retry. Use POST /v1/batch to combine up to 50 calls in 1 request."
  }
}

Response headers:

Retry-After: 2

The body of this refusal carries no retryAfter field — the retry deadline arrives only in the header. The hint field does not arrive on every refusal path: at the platform edge the body consists of code and message. One code combines local pre-dispatch limits with a rate refusal from Bitrix24 after the call was sent, so RATE_LIMITED does not prove that the target call was never dispatched. Both known sources refuse without applying the operation, and retrying a write after Retry-After is safe. See the full matrix in What is safe to retry.

Causes:

• A burst of requests from one address exceeded the platform-edge limit — 60 requests per second, counted per client IP address. Such a refusal arrives with Retry-After: 1 and without X-RateLimit-* headers. Some endpoints carry their own, stricter limit at the edge.
• An endpoint's own per-minute limit is exhausted. By default it is counted per API key. The exceptions, where the counter is one per Bitrix24 account and all of its keys share it: POST /v1/search — 60 per minute, POST /v1/batch — 30 per minute, POST /v1/research — 20 per minute, entity reads — 300 per minute, and the per-entity batch POST /v1/{entity}/batch — 30 per minute. For entity reads the counter runs for each entity and each operation separately: list, search, aggregates, field descriptions, related records and product rows. The numbers above are the platform-wide caps, and they are divided across the backend replicas, so the effective value for your key arrives in the x-ratelimit-limit header.
• The requests-per-second limit on the Bitrix24 side was exceeded. It is counted per Bitrix24 account.

Solution:

• Wait for the time given in the Retry-After header.
• Implement retries with exponential backoff.
• Combine up to 50 calls through POST /v1/batch.
• Cache reference data — fields, statuses, currencies.

`ERROR_LOOP_DETECTED` (429)

Vibecode detects a series of identical errors on one key for one Bitrix24 method and temporarily blocks the request on the Vibecode side, so as not to run up the Bitrix24 counters. Every Nth request is passed through: if the backend has recovered, the block is lifted automatically.

{
  "success": false,
  "error": {
    "code": "ERROR_LOOP_DETECTED",
    "message": "Vibe-side block (not a Bitrix24 limit). 12 failures on crm.deal.list in the last hour.",
    "hint": "Every 50th request will probe for recovery — keep retrying with backoff. If you suspect a platform-side issue (e.g. 5xx during an outage), platform admin can clear the block via POST /api/platform/analytics/circuit-breaker/<apiKeyId>/clear."
  }
}

Response headers:

Retry-After: 60

The body of this refusal carries no retryAfter field — the retry deadline arrives only in the header.

Causes:

• A bug in the client code: a request with identical parameters repeats and consistently fails.
• A platform-wide outage on the Bitrix24 side during the series of requests.

Solution:

• Read message — it names the specific method with the series of errors.
• Find the source of the request in the code and fix the parameters or the logic.
• During a platform outage, first wait out Retry-After. After the cause is resolved, a read can be retried with backoff. Do not retry a write automatically: the platform lets every Nth request through to probe for recovery, so read state first. If the block lasts longer than the outage itself, contact support.
• The route named in the hint field of the response is an internal platform endpoint. Your key cannot call it, and no intervention is required: it is meant for support.

`QUEUE_OVERFLOW` (429)

The queue of requests to Bitrix24 for a specific portal is full: too many calls are already waiting (100 or more by default). The response arrives instantly, within milliseconds, with the Retry-After: N HTTP header (seconds).

{
  "success": false,
  "error": {
    "code": "QUEUE_OVERFLOW",
    "message": "Portal queue overloaded — 100 Bitrix24 calls already pending",
    "userMessage": "Too many concurrent requests to Bitrix24 — retry in a few seconds.",
    "hint": "Honor the Retry-After header. Use exponential backoff with jitter for repeated failures.",
    "retryAfter": 10
  }
}

Solution:

• Retry the request after Retry-After seconds, increasing the pause before each subsequent attempt and adding a random amount to it, so that retries from different clients do not arrive in one wave.
• Reduce concurrency on the client side.
• Combine calls through POST /v1/batch.

`QUEUE_TIMEOUT` (429)

The queue of requests to Bitrix24 for a specific portal is saturated: more than 80 seconds of waiting.

{
  "success": false,
  "error": {
    "code": "QUEUE_TIMEOUT",
    "message": "Portal queue saturated — too many concurrent Bitrix24 calls",
    "userMessage": "Bitrix24 requests have been queued for more than 80 seconds. The Bitrix24 account likely has many concurrent operations.",
    "hint": "The request was NOT sent to Bitrix24 — safe to retry (honor Retry-After, use backoff with jitter). If this is a /search request with a wide date range, try adding \"autoWindow\": false OR narrow the date range to <14 days.",
    "retryAfter": 10
  }
}

The request was NOT sent to Bitrix24 — it is safe to retry.

The number of seconds in userMessage is the wait that applied to this call. Identify this refusal by its QUEUE_TIMEOUT code, and take the retry delay from retryAfter and the Retry-After header.

Solution:

• Retry after retryAfter seconds, increasing the pause before each subsequent attempt and adding a random amount to it.
• Reduce concurrency.
• For /search endpoints, narrow the date range or pass autoWindow: false.
• Combine calls through POST /v1/batch.
• Check the timeout on your side: waiting in the queue counts toward the response time, so the client needs headroom — Client-side timeout.

`TIMEOUT_QUARANTINE` (429)

When the mechanism is enabled for the account, a method that fails to respond three times in a row within the call timeout pauses the "account + method" pair: Vibecode temporarily stops sending requests to it.

{
  "success": false,
  "error": {
    "code": "TIMEOUT_QUARANTINE",
    "message": "Vibe-side block (not a Bitrix24 limit). crm.item.list timed out 3 times in a row on this portal, so calls to it are paused.",
    "hint": "The portal was not answering this method within the call timeout, so every further call would only add load. Honor Retry-After and do NOT shorten your retry interval: an aggressive retry occupies the recovery-probe slot and keeps the method closed for the whole portal longer. One call is let through as a probe every 5 minutes, and the first success lifts the pause immediately. Narrow the request — fewer fields, a smaller page, a tighter filter: a lighter call is what recovers the pair.",
    "retryAfter": 288,
    "scope": "portal"
  }
}

Response headers:

Retry-After: 288

Causes:

• The method consistently fails to respond within the time allowed for the call. The reason is a heavy request: a wide date range, many fields in select, a large page, a filter on a non-indexed field.
• The pause is tracked per "portal + method" pair and does not depend on which key made the call: scope: "portal" means that ALL keys of the account see it, including third-party integrations. Contrast that with OPERATION_TIME_LIMIT and its scope: "apiKey": that refusal is about your key, this one is about the whole account.
• This is a refusal on the Vibecode side, not a Bitrix24 limit: the current request never reached the account, so retrying it is safe even for write methods. This says nothing about the earlier timeout that activated the quarantine.
• The code also arrives inside a 200 response — on the subcalls of POST /v1/batch that Vibecode executes as separate requests (data.errors[<id>]), and on the items of a single-entity batch (data[i].error). A 200 envelope has no Retry-After header for an individual subcall, so the deadline arrives in the retryAfter field, while scope and hint are the same as in a standalone 429.

Solution:

• Wait for the deadline from retryAfter (or from the Retry-After header) and do not shorten the retry interval: while the pause holds, one call every 5 minutes is let through as a recovery probe, and an aggressive retry takes that slot for itself — the method stays closed for the whole account longer than if you had simply waited.
• Add a random amount to the pause, so that retries from different clients do not arrive in one wave.
• Make the call itself lighter: fewer fields in select, a smaller page, a narrower filter, or a narrower date interval. The pause is lifted by the first successful response, so it is a light call that lifts it — a heavy one hits the timeout again and extends the window.
• Do not look for an endpoint that lifts the pause — there is none, and no intervention is required.
• The POST /v1/batch envelope itself is never paused: it combines different methods, and its own latency says nothing about which of them stopped answering.

`OPERATION_TIME_LIMIT` (429)

Bitrix24 paused THIS method for about 5 minutes because the method exhausted the operating-time budget on the account. The refusal arrives both when Bitrix24 itself returns it and when Vibecode rejects the call up front, knowing that the pause is still in effect.

{
  "success": false,
  "error": {
    "code": "OPERATION_TIME_LIMIT",
    "message": "Bitrix24 operation-time limiter banned crm.item.list on this portal, retry in 245s",
    "userMessage": "Bitrix24 paused this request for several minutes: the method exhausted its operating-time limit on the Bitrix24 account. Wait out the Retry-After delay — other methods keep working.",
    "hint": "Bitrix24 banned THIS method on this portal for ~5 minutes because it exhausted the portal's operating-time budget. Honor Retry-After — the same call cannot succeed sooner and retrying earlier only adds load. Other methods on the portal are unaffected; spread heavy reads over time or narrow them (fewer fields, smaller pages, POST /v1/batch).",
    "retryAfter": 245,
    "scope": "apiKey"
  }
}

Response headers:

Retry-After: 245

Causes:

• Bitrix24 counts the operating-time budget over a sliding window.
• The pause is targeted: scope: "apiKey" means that Bitrix24 paused the "your key + this method" pair. Other methods keep working, and other keys of the account can call the same method. Contrast that with TIMEOUT_QUARANTINE and its scope: "portal": there the pause is shared by the whole account.
• The first OPERATION_TIME_LIMIT comes from a Bitrix24 method that was already called. Vibecode then remembers the pause and may reject later requests before dispatch. The code alone therefore does not prove that no effect occurred: retrying a read is safe, but read state before retrying a write.
• The code also arrives inside a 200 response — on the subcalls of POST /v1/batch that Vibecode executes as separate requests (data.errors[<id>]), and on the items of a single-entity batch (data[i].error). A 200 envelope has no Retry-After header for an individual subcall, so the deadline arrives in the retryAfter field, while scope and hint are the same as in a standalone 429. The envelope carries no userMessage field.

Solution:

• Wait for the deadline from retryAfter (or from the Retry-After header): the same call will not go through before that deadline, and retries only add load.
• Spread heavy reads over time instead of firing them all off at once.
• Make the calls lighter: fewer fields in select, a smaller page, or combining calls through POST /v1/batch.

See also

• Error codes
• What is safe to retry
• Retries and error handling in code
• Limits and optimization
• Batch