Коды ошибок

Отклонённый запрос приходит в общем конверте ошибки, и ветвиться в нём нужно по code — не по HTTP-статусу и никогда не по тексту сообщения. Неудачная генерация — отдельный случай: запрос при этом успешен, и причина лежит в другом поле и в другом словаре.

Три словаря, которые легко спутать

Один запрос несёт либо первый словарь, либо третий, никогда оба: успешный статус означает, что API ответил, даже если сама генерация провалилась. Поэтому клиент, который смотрит только на HTTP-статус, неудачных генераций не увидит вовсе.

Ветвиться на 200 здесь мало: повтор POST /v1/generations с тем же Idempotency-Key возвращает ту же самую запись и отвечает 202 независимо от её статуса — в том числе уже FAILED, вместе с её error.reason. Читайте это поле в любом ответе, который несёт запись генерации.

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

HTTP/1.1 400 Bad Request

{
  "error": {
    "code": "invalid_limit",
    "message": "The requested amount is out of range.",
    "user_message": "Запрошено больше допустимого.",
    "request_id": "8f3c1d2e-5a47-4b90-9a1e-2f6b0c7d4e11",
    "details": [
      {
        "field": "limit",
        "reason": "out_of_range",
        "message": "Too big: expected number to be <=100"
      }
    ]
  }
}

• code — стабильный машинный токен. Это единственное поле, по которому клиенту стоит принимать решения.
• message — всегда английский и предназначен для логов, а не для показа пользователю.
• user_message — та же ошибка словами для человека. По умолчанию английская; русская приходит только на запрос с заголовком Accept-Language: ru, а если перевода для кода нет, поле равно message.
• request_id — то, что нужно назвать в поддержке: по нему находится строка лога. Исключение — отказ по лимиту запросов без опознанного вызывающего: такие не пишутся в журнал доступа, и строки по этому идентификатору не будет.
• details — появляется там, где у отказа есть причины по полям: field — путь до поля через точку, reason — что с этим полем не так, из словаря причин ниже, а message — та же причина текстом, для логов.

Ни стека, ни сообщения фреймворка в ответе не бывает. Если вы прислали X-Request-Id, request_id повторит его значение.

Чужой объект отвечает 404

Объект, принадлежащий другому аккаунту, отвечает 404, а не 403: строка, которую вызывающему нельзя видеть, читается как никогда не существовавшая. Поэтому 404 здесь не означает «нет прав» и не лечится повторами: проверяйте идентификатор, а не ключ.

Сообщить о проблеме

Когда генерация вернулась негодной, а error.reason ничего не объясняет, об этом сообщают: POST /v1/generations/{id}/report заводит обращение в поддержку и отвечает 201 с support_request_id и message_id — их и нужно называть в переписке. Маршруту нужна область generations:write.

Денег этот вызов не двигает. Возврат за такую генерацию — решение человека после разбора, и автоматической полосы здесь нет намеренно: баланс после отправки отчёта не меняется, и поля с кредитами в ответе нет.

• text — обязателен, до 2000 символов.
• reason — failure по умолчанию; moderation вдобавок отзывает саму генерацию — кроме той, что уже удерживается на разборе: её отзывает оператор, а обращение всё равно принимается.
• client_msg_id — UUID, по желанию: повтор после потерянного ответа вернёт то же обращение, а не заведёт второе. Тот же идентификатор с другим текстом — 409 с кодом report_replay_mismatch.

Новое обращение с reason: failure по генерации, за которой не осталось неурегулированного — кредиты вернулись автоматически либо не списывались вовсе, — отвечает generation_already_settled: просить по ней нечего. Это не касается moderation — такое обращение принимается и по рассчитанной генерации — и повтора по тому же client_msg_id, который возвращает прежнее обращение. Чужой идентификатор, как и везде, отвечает 404.

Таблица кодов

Прочерк в последней колонке значит, что отдельного совета у кода нет.

Причины в details

Это полный словарь error.details[].reason: он собирается из кода, который эти причины и отдаёт, поэтому новая причина появляется в таблице вместе с собой. Ветвиться по нему можно — токены стабильны, — но решение об ошибке в целом всё равно принимается по error.code.

Сколько запросов осталось в окне, как долго ждать после rate_limited и какие границы у limit — на странице лимитов. Статусы каждой отдельной операции перечислены в справочнике.