Ошибки и коды состояния
Ошибки приходят в JSON, всегда одной формы, и всегда несут стабильный машиночитаемый код. Ветвитесь по коду, а не по сообщению.
Форма
Любой сбой возвращает объект с понятным человеку полем error и стабильным code. Сообщение написано для человека и может быть переформулировано; код — это обязательство, и он не изменится у вас за спиной.
{
"error": "That file is larger than the 200 MB limit on your plan.",
"code": "VALIDATION_FAILED"
}Коды, которые стоит обрабатывать
| Код | HTTP | Что означает |
|---|---|---|
| NOT_AUTHENTICATED | 401 | Bearer-токен отсутствует или некорректен |
| FORBIDDEN | 403 | Ключ действителен, но не имеет права на это действие |
| NOT_ENTITLED | 402 | Тариф аккаунта не включает доступ к API |
| VALIDATION_FAILED | 400 / 413 | Некорректный запрос, неподдерживаемая конвертация или слишком большой файл |
| NOT_FOUND | 404 | Такой задачи нет либо она принадлежит другому аккаунту |
| RATE_LIMITED | 429 | Достигнут часовой лимит. Подождите и повторите. |
| INTERNAL | 500 | Что-то сломалось на нашей стороне. Повтор безопасен. |
Что стоит повторять
429 и 500 стоит повторить с задержкой — с нарастающим интервалом, а не в цикле, потому что повторы расходуют часовой лимит так же, как любые другие запросы.
Всё остальное для этого запроса окончательно. Повтор 400, 402 или 404 даст тот же ответ и потратит лимит на то, чтобы это выяснить.
502 или 503 без тела JSON пришли не от приложения — это стоящий перед ним прокси, и там повтор всегда имеет смысл.