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

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

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

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

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Описание ошибки на английском языке"
  }
}

При ошибках валидации дополнительно возвращается массив errors с указанием конкретных полей:

Ошибка валидации

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body"
  },
  "errors": [
    { "field": "url", "message": "Invalid url: Invalid url" },
    { "field": "steps", "message": "Required" }
  ]
}

Коды ошибок

Клиентские ошибки (4xx)

HTTP	Код	Описание	Что делать
400	`INVALID_JSON`	Невалидный JSON в теле запроса	Проверьте формат JSON
400	`VALIDATION_ERROR`	Ошибка валидации полей	Смотрите массив `errors`
400	`INVALID_TASK_ID`	Невалидный формат ID задачи	Используйте UUID из ответа при создании
400	`INVALID_CATEGORY`	Невалидная категория шага	Проверьте допустимые значения через `GET /steps`
400	`INVALID_INPUT_TYPE`	Невалидный тип входных данных	Проверьте допустимые значения через `GET /steps`
401	`MISSING_API_KEY`	Отсутствует заголовок `Authorization`	Добавьте заголовок `Authorization: Bearer sk-...`
401	`INVALID_AUTH_FORMAT`	Неверный формат заголовка (нет префикса `Bearer`)	Используйте формат `Bearer <ключ>`
401	`INVALID_API_KEY`	API-ключ невалиден	Проверьте правильность ключа в Dashboard
401	`API_KEY_INACTIVE`	API-ключ деактивирован	Активируйте ключ или создайте новый в Dashboard
401	`API_KEY_EXPIRED`	Срок действия ключа истёк	Создайте новый ключ в Dashboard
402	`INSUFFICIENT_BALANCE`	Недостаточно средств на балансе	Пополните баланс
404	`NOT_FOUND`	Ресурс не найден	Проверьте ID задачи или пайплайна
404	`TASK_NOT_FOUND`	Задача не найдена	Проверьте task ID
429	`RATE_LIMIT_EXCEEDED`	Превышен лимит запросов	Подождите и повторите (подробнее)

Серверные ошибки (5xx)

HTTP	Код	Описание	Что делать
500	`INTERNAL_ERROR`	Внутренняя ошибка сервера	Повторите запрос. Если ошибка повторяется — обратитесь в поддержку
502	`UPSTREAM_ERROR`	Сервер обработки недоступен	Повторите через 30-60 секунд

Обработка ошибок в коде

Всегда проверяйте поле success в ответе. При success: false ответ содержит объект error с кодом и описанием.

Рекомендуемый подход

errorHandling.js

async function createTask(data) {
  const response = await fetch("https://premiss.ru/api/v1/tasks", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    body: JSON.stringify(data)
  });
 
  const result = await response.json();
 
  if (!result.success) {
    switch (result.error.code) {
      case "VALIDATION_ERROR":
        // Ошибки валидации — покажите пользователю
        console.error("Ошибки:", result.errors);
        break;
 
      case "INSUFFICIENT_BALANCE":
        // Недостаточно средств — перенаправьте на оплату
        console.error("Пополните баланс");
        break;
 
      case "RATE_LIMIT_EXCEEDED":
        // Превышен лимит — подождите и повторите
        const retryAfter = response.headers.get("Retry-After");
        console.log(`Ожидайте ${retryAfter} секунд`);
        break;
 
      case "MISSING_API_KEY":
      case "INVALID_AUTH_FORMAT":
      case "INVALID_API_KEY":
      case "API_KEY_INACTIVE":
      case "API_KEY_EXPIRED":
        // Проблема с ключом
        console.error("Проверьте API-ключ");
        break;
 
      default:
        // Другие ошибки
        console.error(`${result.error.code}: ${result.error.message}`);
    }
    return null;
  }
 
  return result.data;
}

TTL и истечение задач

Результаты задач хранятся ограниченное время (TTL). По умолчанию — 4 часа после завершения.

После истечения TTL:

Поле expired становится true
Поля input и output становятся null
Метаданные задачи (ID, статус, даты) остаются доступными

Задача с истёкшим TTL

{
  "success": true,
  "data": {
    "id": "1d2f3a4b-...",
    "status": "completed",
    "expired": true,
    "input": null,
    "output": null,
    "expires_at": "2026-02-13T14:30:00.000Z"
  }
}

Используйте webhooks для получения результатов сразу после завершения обработки, чтобы не зависеть от TTL. Параметр ttl при создании задачи позволяет задать время хранения от 0 до 24 часов.