What is safe to retry

The HTTP status and the word retry alone do not answer the main question: will a retry create a duplicate record? Answering that needs two separate characteristics — whether the target call of the method managed to reach Bitrix24, and whether the original request is a read or a write.

Retry-After tells you when the next attempt is allowed from a load standpoint. It does not prove that the previous write was not applied.

Terms

Target call

The target call is the Bitrix24 business method you wanted to execute, for example crm.deal.get or crm.deal.add. A service-level OAuth token refresh does not count as a target call.

For BH_APP_TIMEOUT, the outcome is unknown. The code can come from the agent waiting 14 seconds for headers after sending the request or exhausting its 20-second total budget for a small response; from the Gateway waiting 30 seconds for a first frame or 15 seconds for a pre-commit stream continuation; or from the app itself returning 504 without Content-Type, a shape indistinguishable from an agent refusal. The app may have received the request and called Bitrix24. The code alone cannot establish whether it did.

Read and write

A read does not change data: retrying it is generally safe from a duplicate standpoint. A write creates, changes, deletes, or sends data, so it needs a separate verdict. Determine the operation type by the meaning of the method, not the HTTP verb: a POST can perform a search, while methods like *.add, *.update, *.delete, and *.send change state.

Unknown outcome

"Unknown" means the code alone cannot prove whether the target call managed to produce an effect. The absence of a successful response does not equal the absence of an effect.

Decision rule

• Retry is safe — wait for the stated condition and retry with a limit on the number of attempts.
• Read back first — locate the operation's effect by a stable business key or identifier. Retry the write only if you can prove the effect is absent.
• Do not retry automatically — fix the cause, or hand the case to a human. After the input changes, it is a new deliberate attempt, not a retry of the same request.

If you cannot reliably verify the write's effect, "read back first" means "do not retry automatically". X-Request-Id is for diagnostics and is not an idempotency key.

Code matrix

Why some codes are ambiguous

`RATE_LIMITED`

Delivery is unknown because the same code is shared by local limits and by Bitrix24. Retrying a write after a pause is still safe: the known sources either never send the call or unambiguously reject it by rate without the operation being applied. This does not mean every HTTP 429 response always occurs before the call is sent.

`OPERATION_TIME_LIMIT`

The first rejection with this code is returned by a Bitrix24 method that was already called. After it, Vibecode remembers the pause and may reject following requests before they are sent. That is why the write path takes the more conservative action — verify the effect first.

`TIMEOUT_QUARANTINE`

The current request, stopped by the local pause, is safe. An earlier operation whose timeout triggered the quarantine may have an unknown outcome — this guarantee does not extend to it.

`DB_TRANSIENT`

A transaction rollback in the Vibecode database is not a distributed rollback of Bitrix24. If the external call already completed, the local rollback does not undo its effect.

`BH_APP_STARTING`

No response frame arrived from the app at all, or the agent answered for itself rather than the app. Both say a frame from the app was missing, but neither proves the app's code never saw the request: the connection could have dropped after processing had already started. That is why a write requires reading state back first rather than a blind retry — unlike BH_APP_TIMEOUT below, this code does carry a Retry-After.

`BH_APP_TIMEOUT`

This response can come from the agent waiting 14 seconds for headers after sending the request, exhausting its 20-second total budget for a small buffered response, the Gateway waiting 30 seconds for the first frame or 15 seconds for a pre-commit stream continuation. The app's own 504 without Content-Type has the same shape and becomes this code too. None of these sources proves that no side effect occurred: the app may have called Bitrix24. There is no Retry-After; check the result of a write before retrying it.

Algorithm for reads

1. Recognize the response code.
2. For an authorization error, a business error, or a circuit breaker, fix the cause first.
3. For a transient failure, honor Retry-After; if it is absent, apply bounded exponential backoff with jitter.
4. Retry the read no more than the number of times set by the client.
5. On a persistent failure, stop and pass the time and X-Request-Id (if it was present in the response) to support.

Algorithm for writes

1. Do not use a single retryable-codes list for both reads and writes.
2. If the "Write" cell allows a retry, wait for the stated condition and retry with a limit on the number of attempts.
3. If you need to read back the state, locate exactly the business effect of the original operation by a unique attribute.
4. If the effect is already there, treat the original write as successful and do not retry it.
5. If the effect is verifiably absent, perform a new attempt.
6. If the check is unreliable, stop the automatic retry and resolve the case manually.

A plain GET without a unique criterion does not prove the absence of a duplicate. If the method has its own server-side idempotency key, you can rely on that method's contract; this page itself does not introduce that guarantee.

Classifier example

The classifier takes the operation kind explicitly. It does not try to infer it from the HTTP verb and does not implement a universal readBack: verifying the effect depends on the specific entity.

const VERIFY_WRITE_STATE = new Set([
  'OPERATION_TIME_LIMIT', 'BITRIX_TIMEOUT', 'BITRIX_UNAVAILABLE',
  'POOL_EXHAUSTED', 'DB_TRANSIENT', 'SERVICE_UNAVAILABLE', 'BH_APP_STARTING',
  'BH_APP_TIMEOUT', 'AGENT_WRITE_ALREADY_EXECUTED',
]);

const FIX_BEFORE_RETRY = new Set([
  'BITRIX_ERROR', 'TOKEN_REFRESH_FAILED', 'ERROR_LOOP_DETECTED',
]);

const SAFE_RETRY = new Set([
  'QUEUE_OVERFLOW', 'QUEUE_TIMEOUT', 'RATE_LIMITED', 'CALLER_RATE_LIMITED',
  'TIMEOUT_QUARANTINE', 'LARGE_BODY_BACKEND_BUSY',
]);

function classifyRetry(code, operationKind) {
  if (FIX_BEFORE_RETRY.has(code)) return 'fix_before_retry';
  if (operationKind === 'write' && VERIFY_WRITE_STATE.has(code)) {
    return 'state_verification_required';
  }
  if (SAFE_RETRY.has(code) || operationKind === 'read') return 'retry_with_limit';
  return 'state_verification_required';
}

Handle a code the classifier does not recognize conservatively: a read can be retried with bounded backoff, a write only after verifying the state. A network error without the platform's JSON envelope has the same unknown outcome for a write.

In a batch, the decision is made separately for each item by its own code and the sub-request's semantics. An HTTP 200 on the shared envelope does not mean every item succeeded.

See also

• Error codes
• Limits, queues, and pauses
• Bitrix24 and the platform
• Retries and error handling in code
• Batch
• App runtime environment