Коды ошибок и диагностика

При диагностике сначала зафиксируйте: код состояния HTTP, идентификатор запроса, возвращённый платформой, ID модели, ID задачи, ID материала и исходный код ошибки.

Не фиксируйте API Key, Token сессии разрешения на использование образа или полный адрес загрузки материала; перед отправкой в поддержку платформы удалите конфиденциальные данные.

Значение HTTP-статусов

У 404 три причины — не считайте, что всегда «ID написан неверно»

Это наиболее частая ошибка при диагностике:

Получив 404, сначала проверьте, соответствует ли метод пути, и лишь затем подозревайте ID.

Если видеозадача не найдена, возвращается 400, а не 404

Это место не согласуется с другими интерфейсами и требует особого внимания:

Запрос видеозадачи возвращается со статусом 400 + структура верхнего уровня {code, message, data}, это не 404 и не структура объекта error, описанная ниже.

Три структуры ответа с ошибкой

1. Интерфейсы генерации моделей / изображений / видео — объект error

При ошибке возвращается HTTP не 2xx с объектом error:

{
  "error": {
    "code": "invalid_parameter",
    "message": "请求参数不符合所选模型要求",
    "type": "invalid_request_error",
    "param": "size"
  }
}

code может быть пустой строкой. На практике: и при сбое аутентификации, и при невозможности разобрать JSON тела запроса code равен "". Не определяйте «есть ли ошибка» по пустоте code — ориентируйтесь на код состояния HTTP и в первую очередь читайте message.

type — не стабильное поле классификации. Если нужна классификация, читайте code и не полагайтесь на значение type.

2. Интерфейсы библиотеки материалов — code верхнего уровня

Возвращается HTTP не 2xx, code совпадает с HTTP-статусом:

{ "code": 404, "data": null, "msg": "素材不存在或无权访问" }

3. Запрос видеозадачи — строковый code верхнего уровня

{ "code": "task_not_exist", "message": "task_not_exist", "data": null }

Обратите внимание: здесь code — строка task_not_exist, а не число.

request id: ключевой идентификатор для диагностики

Платформа записывает request id прямо в error.message, искать его в заголовках не нужно:

"message": "Invalid token (request id: 202609221135501066578648268d9d6uXuM5QgH)"

Извлечь одной командой:

curl -s "$LOCOPAL_BASE_URL/v1/models" \
  -H "Authorization: Bearer sk-invalid" \
  | grep -oE 'request id: [A-Za-z0-9]+'

Укажите этот request id при обращении в поддержку — это значительно сократит время диагностики.

Сбой аутентификации

Когда API keys отсутствуют, указаны неверно или истекли, все интерфейсы возвращают HTTP 401 и:

{
  "error": {
    "code": "",
    "message": "Invalid token (request id: ...)",
    "type": "new_api_error"
  }
}

Обратите внимание, что code — пустая строка; именно поэтому выше мы предупреждали «не полагайтесь на code».

Ошибки моделей и генерации

Ошибки библиотеки материалов

Незавершённая проверка материала — не ошибка: запрос возвращает 200, status равен Processing; просто продолжайте опрашивать тот же ID материала.

Пустой вывод рассуждающей модели — тоже не HTTP-ошибка: если вернулся 200, finish_reason равен length, а usage.completion_tokens_details.reasoning_tokens уже занимает весь лимит вывода, следует увеличить квоту вывода или перейти на нерассуждающую модель.

Ошибки разрешения на использование образа

Ограничение частоты запросов и повторные попытки

• 429 означает слишком частые запросы; повторяйте с задержкой (backoff) согласно подсказке и не повторяйте параллельно;
• статус материала рекомендуется запрашивать раз в 5–10 секунд, видеозадачу — раз в 5–15 секунд;
• повторяйте только 429 и кратковременные 5xx; при 400 / 401 / 403 / 404 сразу исправляйте запрос;
• перед повтором сначала запросите по ID задачи / ID материала, чтобы избежать повторного создания и повторного списания средств.

Быстрая самопроверка

1. Соответствует ли Authorization формату Bearer <API Key> и включён ли ещё ключ;
2. Указан ли в запросе домен, заданный сейчас в консоли (по умолчанию https://locopalai.com, для зарубежных моделей может быть https://us-api.locopalai.com);
3. Взят ли model из data[].id ответа /v1/models;
4. Достиг ли status материала значения Active;
5. Является ли адрес референсного изображения / видео публично доступным http(s)-адресом, не зависящим от Cookie или Referer;
6. Не отправлялись ли одна и та же задача / один и тот же материал повторно.

Что приложить при обращении в поддержку

• время запроса и путь эндпоинта;
• код состояния HTTP и полное тело ответа (API Key замаскирован);
• идентификатор запроса, ID задачи или ID материала, возвращённые платформой;
• задействованные ID моделей и параметры;
• минимальный воспроизводимый пример запроса.