Перейти к основному содержанию

Обзор

API APIXO использует два типа кодов ошибок:
  1. HTTP Status Codes — возвращаются сразу при сбое запроса
  2. Task Failure Codes — возвращаются в ответе на запрос статуса при сбое обработки задачи
┌─────────────────────────────────────────────────────────────┐
│                      API Request Flow                        │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  POST /generateTask/{model}                                 │
│         │                                                   │
│         ├── Fail ──→ HTTP Status Code (400/401/429...)      │
│         │           Request rejected immediately             │
│         │                                                   │
│         └── Success ──→ 200 + taskId                        │
│                        Request accepted, task processing    │
│                             │                               │
│                             ▼                               │
│  GET /statusTask/{model}?taskId=xxx                         │
│         │                                                   │
│         ├── state: success ──→ resultUrls                   │
│         │                                                   │
│         └── state: failed ──→ Task Failure Code             │
│                               (failCode/failMsg)             │
│                                                             │
└─────────────────────────────────────────────────────────────┘
ТипКогда возникаетЗначениеПример
HTTP Status CodeСразу при запросеПроблема с самим запросом401 Invalid API Key
Task Failure CodeПри запросе статусаЗапрос принят, но обработка провалиласьSensitiveContentDetected

HTTP Status Codes

КодНазваниеОписаниеДействие
200OKЗапрос выполнен успешноОбрабатывайте ответ как обычно
400Bad RequestНекорректные параметры запросаПроверьте тело запроса
401UnauthorizedНедействительный или отсутствующий API KeyПроверьте API Key
402Payment RequiredНедостаточно средствПополните баланс
403ForbiddenКонтент нарушает политикуИзмените контент
404Not FoundРесурс не найденПроверьте ID модели или задачи
429Too Many RequestsПревышен лимит запросовПодождите и повторите
500Server ErrorВнутренняя ошибка сервераПовторите позже
503Service UnavailableСервис временно недоступенПовторите позже

Task Failure Codes

При сбое задачи в ответе присутствуют failCode и failMsg:
{
  "code": 200,
  "message": "success",
  "data": {
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies."
  }
}

Нарушения политики контента

failCodeОписаниеРешение
SensitiveContentКонтент нарушает политикуИзмените prompt, избегайте чувствительного контента
SensitiveContentDetectedКонтент помечен как нарушениеСкорректируйте контент prompt
InputImageSensitiveContentDetectedВходное изображение содержит нарушениеИспользуйте допустимое изображение
InputOutputSensitiveContentDetectedВходные или выходные данные содержат чувствительный контентПовторите с другим входом
NSFWОбнаружен NSFW-контентИспользуйте контент, соответствующий политике
ProhibitedContentDetectedОбнаружен запрещённый контентИспользуйте другой вход

Ошибки prompt

failCodeОписаниеРешение
PromptLengthExceededPrompt превышает лимитСократите prompt
PromptInvalidНекорректный или отклонённый promptПроверьте формат и содержание prompt

Ошибки изображений/медиа

failCodeОписаниеРешение
ImageFormatIncorrectНекорректный формат изображенияИспользуйте JPEG, PNG или WebP
InvalidImageSizeНекорректные размеры изображенияПроверьте требования к размеру
Upload errorИзображение превышает лимит 10MBСожмите до менее 10MB
INVALID_IMAGE_URLНет доступа к URL изображенияПроверьте доступность URL
INVALID_LORA_URLНе удаётся загрузить модель LoRAПроверьте URL LoRA

Лимиты и квоты

failCodeОписаниеРешение
RateLimitedЛимит запросов, повторите позжеУменьшите частоту, подождите и повторите
RateLimitExceededПревышен лимит запросовПовторите позже
InsufficientQuotaНедостаточная квотаПроверьте баланс

Ошибки обработки и системы

failCodeОписаниеРешение
TimeoutТаймаут ответаПовторите позже
Task TimeOutЗадача истекла, генерация не удаласьПерейдите к другой задаче
BadRequestОтсутствуют обязательные параметрыПроверьте параметры запроса
MissingParameterОтсутствует обязательный параметрСм. документацию API, добавьте параметр

Примеры ответов при ошибках

HTTP-ошибка (немедленный ответ)

400 — Ошибка параметров
{
  "code": 400,
  "message": "Prompt exceeds provider limit (max 2000 chars)",
  "data": null
}
401 — Ошибка аутентификации
{
  "code": 401,
  "message": "Invalid or missing API key",
  "data": null
}
429 — Превышен лимит
{
  "code": 429,
  "message": "Provider rate limited, please retry later",
  "data": null
}
504 — Таймаут
{
  "code": 504,
  "message": "Provider timeout, please retry later",
  "data": null
}

Ошибка задачи (при запросе статуса)

Нарушение политики контента
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "SensitiveContentDetected",
    "failMsg": "Your content was flagged by OpenAI as violating content policies.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}
NSFW-контент
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "NSFW",
    "failMsg": "NSFW, Try different input please.",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}
Ошибка формата изображения
{
  "code": 200,
  "message": "success",
  "data": {
    "taskId": "task_12345678",
    "state": "failed",
    "failCode": "ImageFormatIncorrect",
    "failMsg": "Image format is incorrect",
    "createTime": 1767965610929,
    "completeTime": 1767965652317
  }
}

Рекомендации по обработке ошибок

Только 429, 500 и 504 подходят для автоматического повтора. Все остальные ошибки требуют исправления запроса.

1. Стратегия повторов

Тип ошибкиПовторять?Стратегия
400 (Ошибка параметров)НетИсправьте параметры, затем повторите
401 (Ошибка аутентификации)НетПроверьте API Key
429 (Лимит)ДаЭкспоненциальный backoff, подождите 60с и повторите
500 (Ошибка сервера)ДаЭкспоненциальный backoff, макс. 3 раза
504 (Таймаут)ДаПодождите и повторите, макс. 3 раза
Нарушение контентаНетИзмените контент и повторите
Ошибка изображенияНетИсправьте изображение и повторите

2. Пример экспоненциального backoff

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.code === 429 || error.code >= 500) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(resolve => setTimeout(resolve, delay));
      } else {
        throw error;
      }
    }
  }
  throw new Error('Max retries exceeded');
}

3. Советы по модерации контента

Модерация контента выполняется вышестоящими провайдерами ИИ. Обжаловать нарушения через APIXO нельзя — измените контент и отправьте снова.
Чтобы избежать ошибок модерации:
  • Избегайте насилия, порнографии, политически чувствительного контента
  • Убедитесь, что входные изображения соответствуют политике
  • Используйте чёткие, конкретные описания, избегайте двусмысленности
  • Сначала тестируйте на простом, безопасном контенте

4. Мониторинг и логирование

Рекомендуется логировать для отладки:
  • taskId — уникальный идентификатор задачи
  • failCode — код ошибки
  • failMsg — сообщение об ошибке
  • Параметры запроса (без секретов)

Ошибки конкретных провайдеров

OpenAI

failCodeОписание
SensitiveContentDetectedКонтент помечен OpenAI как нарушение
InputImageSensitiveContentDetectedИзображения с реальными людьми не поддерживаются

MidJourney

failCodeОписание
Website TimeOutСайт MidJourney не отвечает после нескольких попыток
INVALID_TASK_IDНекорректный ID предыдущей задачи для upscale/vary

Seedream (ByteDance)

failCodeОписание
outputimagesensitivecontentdetectedВыходное изображение содержит чувствительный контент
InvalidImageSizeНекорректные размеры изображения

FAQ

В: Получил ошибку 429, сколько ждать?
О: Подождите 60 секунд и повторите, или используйте экспоненциальный backoff.
В: Как избежать ошибки PromptLengthExceeded?
О: У каждой модели свой лимит длины prompt, смотрите документацию. Обычно лучше держать до 2000 символов.
В: Можно ли обжаловать ошибку SensitiveContentDetected?
О: Это результат модерации провайдера ИИ. Рекомендуется изменить контент и отправить снова.
В: Что делать с ошибками 5xx?
О: Это временные ошибки сервера. Используйте экспоненциальный backoff, макс. 3 раза. Если сохраняются — обратитесь в поддержку.
Почему статус задачи возвращает 200, но state равен failed? HTTP 200 означает, что сам запрос к API прошёл успешно, а задача генерации провалилась. Реальная ошибка в failCode и failMsg, а не в HTTP-статусе.
В: Почему статус задачи возвращает 200, но state равен failed? О: HTTP 200 означает, что запрос к API успешен, а выполнение задачи провалилось (например, нарушение контента). Информация об ошибке в failCode и failMsg.

Поддержка

Постоянные ошибки? Обращайтесь в поддержку с указанием:
  • taskId — ID неудавшейся задачи
  • failCode — код ошибки
  • Параметры запроса (без секретов)
  • Время возникновения ошибки
Техподдержка: support@apixo.ai