Обзор
API APIXO использует два типа кодов ошибок:
- HTTP Status Codes — возвращаются сразу при сбое запроса
- 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
| Код | Название | Описание | Действие |
|---|
200 | OK | Запрос выполнен успешно | Обрабатывайте ответ как обычно |
400 | Bad Request | Некорректные параметры запроса | Проверьте тело запроса |
401 | Unauthorized | Недействительный или отсутствующий API Key | Проверьте API Key |
402 | Payment Required | Недостаточно средств | Пополните баланс |
403 | Forbidden | Контент нарушает политику | Измените контент |
404 | Not Found | Ресурс не найден | Проверьте ID модели или задачи |
429 | Too Many Requests | Превышен лимит запросов | Подождите и повторите |
500 | Server Error | Внутренняя ошибка сервера | Повторите позже |
503 | Service 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 | Описание | Решение |
|---|
PromptLengthExceeded | Prompt превышает лимит | Сократите 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