Обработка ошибок API

Формат ответа об ошибке

Все ошибки API возвращаются в стандартном формате:

{
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "error": {
    "code": "PAYMENT_REQUIRED",
    "message": "Insufficient wallet balance. Please top up your wallet."
  }
}

Обработка по типам ошибок

401 Unauthorized

API-ключ невалиден, отозван или истёк. Проверьте правильность ключа. Если ключ недавно ротировался — убедитесь, что сервис использует новый ключ. Retry бесполезен.

402 Payment Required

Недостаточно средств на кошельке (PAYMENT_REQUIRED) или превышен spend limit организации (SPEND_LIMIT_EXCEEDED). Проверьте error.code для определения причины. Пополните кошелёк или увеличьте лимит. Retry бесполезен до устранения причины.

429 Rate Limited

Превышен лимит запросов в минуту. Используйте exponential backoff с учётом заголовка Retry-After. Не отправляйте запросы до истечения указанного периода.

503 Service Unavailable

Сервис временно недоступен. Retry с exponential backoff. Если ошибка сохраняется — проверьте страницу статуса.

Retry-логика (псевдокод)

async function callWithRetry(request, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fetch(request);

    if (response.ok) return response;

    const status = response.status;

    // Non-retryable errors
    if ([401, 402, 403, 422].includes(status)) {
      throw new ApiError(status, await response.json());
    }

    // Retryable errors: 429, 500, 503
    if (attempt < maxRetries) {
      const retryAfter = response.headers.get('Retry-After');
      const delay = retryAfter
        ? parseInt(retryAfter, 10) * 1000
        : Math.min(1000 * 2 ** attempt, 30000);
      await sleep(delay);
    }
  }
  throw new Error('Max retries exceeded');
}

Использование request_id для отладки

Все ответы API содержат request_id. Логируйте его вместе с error.code и error.message — это ускоряет диагностику при обращении в поддержку.

const response = await fetch(url, options);
const body = await response.json();

if (!response.ok) {
  console.error('API error', {
    request_id: body.request_id,
    code: body.error?.code,
    message: body.error?.message,
  });
}