Skip to Content
API и интеграцииОшибки и лимиты

Ошибки и лимиты

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

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

{ "error": "error_code", "message": "Человекочитаемое описание ошибки.", "details": {} }
ПолеТипОписание
errorstringМашинный код ошибки (для логики)
messagestringОписание (для логирования/отображения)
detailsobjectДополнительные данные (опционально)

HTTP-коды

КодОшибкаОписание
400invalid_requestНевалидные данные, неправильный формат
401missing_authorization, invalid_api_keyОтсутствует или невалидный API-ключ
402insufficient_tokensНедостаточно искр
403forbiddenНет доступа (ресурс принадлежит другому пользователю)
404not_foundРесурс не найден
413image_too_largeИзображение превышает лимит
422invalid_requestОшибка валидации (webhooks, параметры)
429rate_limit_exceededПревышен лимит запросов
500*_failedВнутренняя ошибка сервера
503generation_unavailableСервис генерации временно недоступен

Детали по каждому коду

401 Unauthorized

{ "error": "missing_authorization", "message": "Authorization header required. Use: Authorization: Bearer ak_..." }
{ "error": "invalid_api_key", "message": "Invalid or revoked API key" }

Что делать: Проверьте заголовок Authorization: Bearer ak_.... Убедитесь, что ключ не отозван.

402 Payment Required

{ "error": "insufficient_tokens", "message": "Not enough sparks. Balance: 2, required: 4.", "details": {"available": 2, "required": 4} }

Что делать: Пополните баланс на app.aidentika.com . Проверьте текущий баланс через GET /balance.

403 Forbidden

{ "error": "forbidden", "message": "Action belongs to another user" }

Что делать: Убедитесь, что action_id принадлежит вашему аккаунту.

413 Payload Too Large

{ "error": "image_too_large", "message": "Image exceeds size limit" }

Что делать: Уменьшите изображение. Максимальный размер base64-строки: ~15 МБ.

429 Too Many Requests

{ "error": "rate_limit_exceeded", "message": "Rate limit exceeded. Limit: 100 requests/minute.", "details": {"limit": 100, "reset_at": 1772000000} }

Заголовки ответа:

X-RateLimit-Limit: 100 X-RateLimit-Remaining: 0 X-RateLimit-Reset: 1772000000 Retry-After: 60

Что делать: Подождите до reset_at или используйте Retry-After. Если нужен более высокий лимит — свяжитесь с поддержкой: @aidentika_support_bot .

503 Service Unavailable

{ "error": "generation_unavailable", "message": "AI provider not configured" }

Что делать: Сервис генерации временно недоступен. Повторите позже.


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

import time import requests def api_request(method, path, **kwargs): resp = requests.request(method, f"{BASE_URL}{path}", headers=headers, **kwargs) if resp.status_code == 429: retry_after = int(resp.headers.get("Retry-After", 60)) time.sleep(retry_after) return api_request(method, path, **kwargs) if resp.status_code == 402: error = resp.json() print(f"Недостаточно искр: {error['details']['available']}/{error['details']['required']}") return None if resp.status_code >= 400: error = resp.json() raise Exception(f"API error {resp.status_code}: {error['error']}{error['message']}") return resp.json()

Рекомендации

  1. Всегда проверяйте HTTP-код ответа, не только тело
  2. Обрабатывайте 429 с exponential backoff или Retry-After
  3. Проверяйте баланс перед пакетной генерацией через GET /balance
  4. Логируйте error и message для отладки
  5. Не парсите message для логики — используйте поле error (машинный код)

Лимиты

ПараметрЗначение
Запросов в минуту (по ключу)100 (по умолчанию)
Активных API-ключей10 на аккаунт
Активных webhooks5 на аккаунт
Активных загрузок (uploads)20 на аккаунт
Время жизни upload1 час
Изображений в запросе5
Размер base64~15 МБ
Глубина редактирований99
Срок действия result_url30 дней

Нужен более высокий лимит? Напишите в поддержку: @aidentika_support_bot .