HiAPI возвращает 403 без прав на модель: руководство по диагностике и исправлению

При вызове интерфейса HiAPI /v1/tasks в случае получения HTTP 403 тело ответа обычно имеет такую структуру: {"error": {"code": "permission_denied", "message": "...", "request_id": "...", "type": "hiapi_error"}}. Это означает, что ваш API Key сам по себе действителен, аутентификация уже пройдена, но этому Key не разрешён вызов запрошенной вами модели или интерфейса — это отличается от 401 «Key недействителен или отсутствует»: 401 — это когда личность даже не распознана, а 403 — когда распознана, но этому Key не разрешён доступ к текущему ресурсу. В большинстве случаев исправление 403 очень простое: проверьте соответствие Key и модели и повторите попытку с другим Key, у которого есть права.

Распространённые причины

1. API Key не авторизован для использования запрошенной модели — в официальной документации 403 определяется именно как «у API-ключа нет этих прав», это наиболее частый сценарий, обычно возникает при вызове одной и той же Key моделей за пределами её области прав.
2. Использован не тот Key — например, должен был использоваться основной Key, но по ошибке применён Key другого аккаунта или проекта с меньшей областью прав; при копировании и вставке также легко добавить лишние пробелы или обрезать Key.
3. Путаница между «ключ недействителен» (401) и «у ключа нет прав» (403) — в сообщениях об ошибках обоих типов может встречаться слово «права», и диагностика по одной и той же логике уведёт в неверном направлении; конкретный способ различения приведён ниже.

Шаги исправления

1. Сначала убедитесь, что действительно вернулся 403, а не 401 — смотрите на сам HTTP-статус, а не только на текст сообщения об ошибке, поскольку код ошибки permission_denied может появляться и при 401, и при 403; различать нужно по статусу, а не по тексту.
2. Перейдите в управление API-ключами и проверьте принадлежность этой Key — убедитесь, что фактически используемый в запросе Key действительно тот, что ожидался, а не Key тестового аккаунта, старого проекта или чужого аккаунта.
3. Проверьте, входит ли текущая модель в доступный диапазон этой Key — можно свериться с документацией по аутентификации и ценами HiAPI, чтобы убедиться, что модель действительно существует и доступна вам для вызова; если сам ID модели написан с ошибкой или модель уже выведена из эксплуатации, ошибка должна быть с другим кодом, а не permission_denied — это можно использовать для уточнения типа проблемы.
4. Возьмите Key с подтверждёнными правами и повторите попытку с полностью теми же остальными параметрами, чтобы проверить, исчезает ли проблема при смене Key.
5. Если после проверки и Key, и модель в порядке, а 403 стабильно воспроизводится, зафиксируйте request_id из тела ответа и обратитесь в поддержку; не повторяйте один и тот же запрос многократно, не выяснив причину.

Минимальный пример проверки

Ниже приведён запрос, который вызовет 403, и повторная попытка после исправления, показывающие реальную структуру ответа в обоих состояниях (замените MODEL_ID на модель, которую вы фактически вызываете и в правах на которую сомневаетесь):

curl https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "prompt": "a simple test prompt"
  }'

Ответ при отсутствии прав:

{
  "error": {
    "code": "permission_denied",
    "message": "Текущий API Key пока не может использовать эту модель, проверьте права или замените Key.",
    "request_id": "req_xxxxxxxx",
    "type": "hiapi_error"
  }
}

Повторная попытка с Key, у которого есть права, при неизменных остальных параметрах:

{
  "code": 200,
  "data": { "taskId": "tk-hiapi-xxxxxxxx" },
  "message": "success"
}

Можно заметить, что структуры двух ответов различаются: ошибки уровня аутентификации/прав, такие как 403, единообразно оборачиваются объектом в error; а ошибки, возникающие после того, как Key прошёл проверку прав и действительно дошёл до оценки конкретных бизнес-правил (например, 402 при недостатке баланса), возвращаются в плоской структуре code / data / message. По тому, какая структура вернулась, можно в целом определить, заключается ли проблема в уровне аутентификации и прав или в уровне конкретных бизнес-правил.

Связанные внутренние ссылки

• Управление API-ключами
• Документация по аутентификации
• Цены HiAPI

FAQ

В чём конкретно разница между 403 и 401? 401 означает, что Key сам по себе недействителен или в запросе вообще нет Key — этап аутентификации личности не пройден. 403 означает, что аутентификация пройдена (Key действителен), но этому Key не разрешено использование запрошенной вами модели или ресурса. Структура тела ответа у обоих одинакова (объект, обёрнутый в error.code), ключ к различению — сам HTTP-статус, а не текст в сообщении об ошибке.

После смены Key всё ещё 403 — это проблема с аккаунтом? Сначала убедитесь, что новый Key действительно принадлежит тому же аккаунту или проекту с правами и что при копировании и вставке не появилось лишних пробелов, переводов строк или обрезки. Если после проверки проблема воспроизводится, обратитесь в поддержку, приложив request_id из тела ответа.

Может ли 403 быть из-за недостатка баланса? Нет. Недостаток баланса соответствует другому коду ошибки (INSUFFICIENT_QUOTA, HTTP 402) и не связан с правами — 403 лишь означает «имеет ли этот Key право вызывать эту модель» и не зависит от суммы на балансе аккаунта.

Если в сообщении об ошибке есть слово «права», это обязательно 403? Не обязательно. Код ошибки permission_denied может появляться и при 401, и при 403; нельзя судить только по текстовым ключевым словам, нужно смотреть непосредственно на сам HTTP-статус.