# Retries and error handling in code

A summary of retry strategies for temporary-refusal codes, plus ready-made response handlers in JavaScript, Python and PHP.

The summary table of all Vibecode API codes — [Error codes](/docs/errors).

## Retries and pauses

Summary of the codes that signal a temporary problem and warrant a retry:

| Code | HTTP | Retry strategy |
|-----|------|--------------------|
| [`RATE_LIMITED`](/docs/errors/limits#rate_limited-429), [`QUEUE_OVERFLOW`](/docs/errors/limits#queue_overflow-429), [`QUEUE_TIMEOUT`](/docs/errors/limits#queue_timeout-429) | 429 | Retry after `Retry-After`, then with a growing pause and random jitter |
| `LARGE_BODY_BACKEND_BUSY` | 429 | Retry after `Retry-After` with random jitter added to the pause. The request was not executed and changed no state — the retry is safe for writes too |
| [`OPERATION_TIME_LIMIT`](/docs/errors/limits#operation_time_limit-429) | 429 | Retry strictly after `Retry-After`: before that moment the same call will not go through. `scope: "apiKey"` — the pause applies only to the calling key |
| [`TIMEOUT_QUARANTINE`](/docs/errors/limits#timeout_quarantine-429) | 429 | Retry after `Retry-After` with random jitter added to the pause, and **without shortening the interval**: an early retry extends the pause. `scope: "portal"` — the pause is shared by all keys of the portal |
| [`ERROR_LOOP_DETECTED`](/docs/errors/limits#error_loop_detected-429) | 429 | Retry after `Retry-After`. The body carries no `retryAfter` field. First find the cause: the code means a series of identical refusals on one key. The platform lets every Nth retry through as a recovery probe |
| [`BITRIX_TIMEOUT`](/docs/errors/platform#bitrix_timeout-503) | 503 | A longer pause before the retry than for 429. For a write — re-read the entity first: the change may already have been applied |
| [`BITRIX_UNAVAILABLE`](/docs/errors/platform#bitrix_unavailable-502) | 502 | This is a 5xx from Bitrix24 itself or a network problem between Vibecode and the portal, not a queue overload: the response carries no `Retry-After` header, so retry with exponential backoff. For a write — first check whether it was applied |
| `POOL_EXHAUSTED`, `DB_TRANSIENT`, `SERVICE_UNAVAILABLE` | 503 | Retry after `retryAfter` (the same value as the `Retry-After` header) — a few seconds. For `DB_TRANSIENT` the transaction is rolled back entirely, so the retry is safe for writes too. For `SERVICE_UNAVAILABLE` the outcome may remain unknown — for non-idempotent operations check the entity state before retrying |
| [`INTERNAL_ERROR`](/docs/errors/platform#internal_error-500) | 500 | Retry the request. An error that reproduces consistently is not fixed by a retry — submit a ticket with the request time and the `X-Request-Id` header |

The table covers the refusals that arrive on any endpoint. The remaining temporary states — installing an application through the connector module, waiting for a Bitrix24 update, freezing a key while an account is being deleted — are described by the code's row in the [summary table](/docs/errors), which says whether a retry changes anything.

## Error handling in code

The handlers below limit the number of attempts. The limit is mandatory: a refusal that outlasts your patience becomes a series of identical requests if you retry endlessly, and the platform shuts that series down with the [`ERROR_LOOP_DETECTED`](/docs/errors/limits#error_loop_detected-429) code.

### JavaScript

```javascript
const MAX_ATTEMPTS = 5;

async function vibeRequest(url, options = {}, attempt = 1) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'X-Api-Key': process.env.VIBE_API_KEY,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  const data = await response.json();

  if (!data.success) {
    const { code, message, retryAfter } = data.error;
    const canRetry = attempt < MAX_ATTEMPTS;

    switch (code) {
      case 'RATE_LIMITED':
      case 'QUEUE_TIMEOUT': {
        if (!canRetry) throw new Error(`${code}: the refusal persists for ${MAX_ATTEMPTS} attempts in a row`);
        const wait = retryAfter ?? Number(response.headers.get('Retry-After') ?? 1);
        await new Promise(r => setTimeout(r, wait * 1000));
        return vibeRequest(url, options, attempt + 1);
      }

      case 'BITRIX_UNAVAILABLE':
        if (!canRetry) throw new Error(`${code}: the refusal persists for ${MAX_ATTEMPTS} attempts in a row`);
        await new Promise(r => setTimeout(r, 5000));
        return vibeRequest(url, options, attempt + 1);

      case 'MISSING_API_KEY':
      case 'INVALID_API_KEY':
        throw new Error('Check the API key');

      default:
        throw new Error(`${code}: ${message}`);
    }
  }

  return data;
}
```

### Python

```python
import os
import time
import requests

MAX_ATTEMPTS = 5

def vibe_request(url, method="GET", json_data=None, attempt=1):
    headers = {
        "X-Api-Key": os.environ["VIBE_API_KEY"],
        "Content-Type": "application/json",
    }

    response = requests.request(method, url, headers=headers, json=json_data)
    data = response.json()

    if not data.get("success"):
        err = data.get("error", {})
        code = err.get("code")
        message = err.get("message")
        retry_after = err.get("retryAfter") or int(response.headers.get("Retry-After", 1))
        can_retry = attempt < MAX_ATTEMPTS

        if code in ("RATE_LIMITED", "QUEUE_TIMEOUT"):
            if not can_retry:
                raise Exception(f"{code}: the refusal persists for {MAX_ATTEMPTS} attempts in a row")
            time.sleep(retry_after)
            return vibe_request(url, method, json_data, attempt + 1)

        if code == "BITRIX_UNAVAILABLE":
            if not can_retry:
                raise Exception(f"{code}: the refusal persists for {MAX_ATTEMPTS} attempts in a row")
            time.sleep(5)
            return vibe_request(url, method, json_data, attempt + 1)

        raise Exception(f"{code}: {message}")

    return data
```

### PHP

```php
const MAX_ATTEMPTS = 5;

function vibeRequest(string $url, string $method = 'GET', ?array $data = null, int $attempt = 1): array {
    $ch = curl_init($url);
    curl_setopt_array($ch, [
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_CUSTOMREQUEST => $method,
        CURLOPT_HTTPHEADER => [
            'X-Api-Key: ' . getenv('VIBE_API_KEY'),
            'Content-Type: application/json',
        ],
    ]);
    if ($data !== null) {
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
    }
    $body = json_decode(curl_exec($ch), true);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($body === null) {
        throw new Exception("HTTP error: $httpCode");
    }

    if (empty($body['success'])) {
        $errCode = $body['error']['code'] ?? 'UNKNOWN';
        $errMsg = $body['error']['message'] ?? 'Unknown error';
        $retryAfter = $body['error']['retryAfter'] ?? 1;
        $canRetry = $attempt < MAX_ATTEMPTS;

        if (in_array($errCode, ['RATE_LIMITED', 'QUEUE_TIMEOUT'], true)) {
            if (!$canRetry) {
                throw new Exception("$errCode: the refusal persists for " . MAX_ATTEMPTS . ' attempts in a row');
            }
            sleep((int) $retryAfter);
            return vibeRequest($url, $method, $data, $attempt + 1);
        }

        if ($errCode === 'BITRIX_UNAVAILABLE') {
            if (!$canRetry) {
                throw new Exception("$errCode: the refusal persists for " . MAX_ATTEMPTS . ' attempts in a row');
            }
            sleep(5);
            return vibeRequest($url, $method, $data, $attempt + 1);
        }

        throw new Exception("$errCode: $errMsg");
    }

    return $body;
}
```

## See also

- [Error codes](/docs/errors)
- [Limits, queues, and pauses](/docs/errors/limits)
- [Bitrix24 and the platform](/docs/errors/platform)
- [Limits and optimization](/docs/optimization)
- [Batch](/docs/batch)
- [CLI and cURL](/docs/cli)