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

Решайте, ретраить запрос, остановиться или исправить его, сначала по HTTP status, потом по error.code. Сохраняйте x-request-id у каждого неуспешного запроса, чтобы повторяющиеся сбои было проще диагностировать и эскалировать.

Ретрай, остановка или исправление запроса

Сначала читайте HTTP status

Для неуспешных ответов ожидайте объект error в JSON body:

type GonkaErrorResponse = {
  error: {
    message: string;
    type?: string;
    code?: string;
  };
};

Сначала ветвите логику по HTTP status, потом по error.code. Используйте error.message только для логов и UI. Не стройте retry-логику по тексту сообщения. Если body отсутствует или не парсится как JSON, всё равно ветвите по HTTP status и сохраняйте x-request-id.

Вынесите решение в один helper

type GonkaErrorResponse = {
  error?: {
    message?: string;
    type?: string;
    code?: string;
  };
};

function decideGonkaAction(status: number, code?: string) {
  if (status === 401 || status === 403) return "fix-auth-or-account";
  if (status === 429 && code === "insufficient_quota") return "show-billing-state";
  if (status === 429) return "retry-with-backoff";
  if (status >= 500) return "retry-then-escalate";
  return "fix-request";
}

async function sendRequest() {
  const response = await fetch("https://api.gonkagate.com/v1/chat/completions", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.GONKAGATE_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "qwen/qwen3-235b-a22b-instruct-2507-fp8",
      messages: [{ role: "user", content: "Hello, GonkaGate!" }],
    }),
  });

  const requestId = response.headers.get("x-request-id") ?? "unknown";
  const payload = (await response.json().catch(() => ({}))) as GonkaErrorResponse;

  if (response.ok) {
    console.log("success");
    return;
  }

  const action = decideGonkaAction(response.status, payload.error?.code);

  console.error({
    action,
    requestId,
    status: response.status,
    type: payload.error?.type,
    code: payload.error?.code,
    message: payload.error?.message,
  });
}

sendRequest().catch(console.error);

Используйте один общий helper, чтобы все вызовы принимали одно и то же решение для одного и того же класса ошибки.

Что сохранить для саппорта

Сохраняйте этот пакет, если запрос падает повторно или нужна помощь саппорта:

• x-request-id
• HTTP status, error.type, error.code и error.message
• model ID, latency и число retry
• sanitized request context
• контекст баланса или троттлинга для сбоев 429

Если повторяющиеся 5xx, timeout или connection reset не исчезают после лимита retry, эскалируйте с этим пакетом вместо того, чтобы бесконечно увеличивать число повторов.

Частые ошибки

• Ретраить любой 429. insufficient_quota — это состояние биллинга, а не retryable throttling.
• Ветвить логику по error.message, а не по HTTP status и error.code.
• Прятать 401, 403 или проблемы с балансом за фоновыми ретраями.
• Давать воркерам, cron-задачам или вкладкам браузера бесконечно ретраить.

См. также

• Обработка rate limits в GonkaGate для точных правил по 429, Retry-After, backoff и traffic shaping.
• Аутентификация и API-ключи для проверки Bearer-заголовка, жизненного цикла ключей и ошибок состояния аккаунта.
• Pricing для правил предоплаченного USD-баланса и биллинга вокруг insufficient_quota.
• POST /v1/chat/completions — Создать chat completion для точного контракта POST /v1/chat/completions и endpoint-level примеров.