Ошибки и повторы

Язык сообщений об ошибках

Тексты ошибок, предназначенные для людей, можно получать на выбранном вами языке. Это касается трёх полей: msg в ответе, errorMessage неудачной задачи (и в recordInfo, и в доставках webhook) и error.message в объектах ошибок совместимых API — одинаково для форматов OpenAI, Anthropic и Google Gemini. По умолчанию используется английский. Поддерживаемые коды языков: en, zh-Hant, ja, ko, de, fr, es, pt-BR, ru.

Меняется только текст для чтения. Значения code и errorCode, type и code в слое совместимости с OpenAI, code и status в слое совместимости с Gemini, а также имена полей одинаковы на любом языке. Ветвите логику только по кодам и не разбирайте текст; в логах и оповещениях сохраняйте code и request_id. Заголовок ответа Content-Language показывает, какой язык фактически использован. Например, для того же 40201 (недостаточный баланс) msg по умолчанию — «Insufficient balance», а с Accept-Language: ja msg приходит на японском; code при этом остаётся 40201.

Язык выбирается в таком порядке:

• Заголовок Accept-Language — действует только для этого запроса. Применяется стандартное взвешивание HTTP: выбирается распознанный язык с наибольшим значением q. Региональные варианты сводятся к своему языку: de-DE — к de, pt-PT — к pt-BR, zh-TW, zh-HK и zh-Hant — к zh-Hant. Китайский доступен только в традиционных иероглифах, поэтому zh-CN и zh-Hans не соответствуют ни одному языку, и проверяется следующий кандидат. * означает отсутствие предпочтения.
• Настройка аккаунта — в консоли, «Настройки → Язык ошибок API». Она действует для всех запросов с API-ключом этого аккаунта, в которых нет распознаваемого заголовка Accept-Language. Большинство серверных SDK и curl по умолчанию этот заголовок не отправляют, поэтому на практике это самый распространённый способ. У доставок webhook нет заголовка запроса, и они всегда следуют настройке аккаунта.
• Если нет ни того, ни другого, используется английский.

# Default: no Accept-Language, no account setting
HTTP/1.1 402 Payment Required
Content-Language: en

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }

# The same request with one extra header
curl -X POST https://api.spicyapi.ai/api/v1/jobs/createTask \
  -H "Authorization: Bearer $SPICY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $SPICY_IDEMPOTENCY_KEY" \
  -H "Accept-Language: ja" \
  --data "$TASK_PAYLOAD"

HTTP/1.1 402 Payment Required
Content-Language: ja

{ "code": 40201, "msg": "残高が不足しています", "request_id": "req_…" }

Ошибки без повтора

400, 401, 403, 404, 40201, 40202 и 40301–40303 не изменятся до исправления входных данных, ключа, прав, баланса или лимита. Код 413 означает слишком большое тело: не повторяйте его без изменений, уменьшите тело или используйте загрузку медиа.

Ошибки с повтором

Для 429 соблюдайте Retry-After. Для HTTP 500/503 и бизнес-кодов 500/50301 используйте экспоненциальную задержку с jitter. Код 409 зависит от операции: повторяйте только media pending или редкий конкурентный конфликт createTask с тем же Idempotency-Key и неизменным payload. Конфликт ключа с другим payload повторять нельзя.

При сетевой ошибке createTask повторно используйте тот же Idempotency-Key. Тот же ключ с другим payload вернет 409.

Оплата

Запрос, отклоненный до создания задачи, не оплачивается. После создания failed, expired и исторические записи canceled полностью освобождают резерв. Новую принятую задачу отменить нельзя; только succeeded списывается по фактическому использованию.