Проблема API-ключей, которые никогда не истекают
Ключ, выданный много лет назад, ни разу не заменённый и до сих пор действующий, это не удобство. Это риск, на который никто не смотрел уже много лет.
Почему мы публикуем коды ошибок, а не скрываем их
Неудачный запрос к API и так портит кому-то день. Становится хуже, когда вернувшийся код ошибки нигде не объяснён и разработчику, который его отлаживает, приходится гадать, означает ли 400 неправильный параметр, отсутствующее обязательное поле или что-то совсем другое, что просто имеет тот же код статуса, что и три других не связанных между собой проблемы. Недокументированная ошибка не просто неудобство. Она превращает пятиминутное исправление в расследование без конца, которое иногда заканчивается обращением в поддержку, хотя его можно было избежать, прочитав страницу, которая должна была существовать.
Мы открыто публикуем наши коды ошибок в документации по ошибкам, где указано, что на самом деле означает каждый из них и что обычно его вызывает, рядом со страницами об аутентификации и лимитах запросов, которые описывают другие причины, по которым запрос может завершиться неудачей. Цель в том, чтобы при сбое ответ был на расстоянии одной страницы, а не догадкой, основанной на общих соглашениях о кодах статуса HTTP, которые могут точно соответствовать тому, что сделала именно наша система, а могут и не соответствовать.
Сокрытие подробностей об ошибках, даже непреднамеренное, через скудную документацию, иногда объясняется разумным на первый взгляд соображением: если точно раскрыть, почему запрос не удался, это теоретически может помочь тому, кто ищет слабые места в API. На практике это опасение редко оправдывает реальную цену. Подавляющее большинство тех, кто сталкивается с кодом ошибки, это добросовестные разработчики, которые пытаются исправить собственную интеграцию, а не злоумышленники, изучающие поверхность атаки. Подстраивать документацию об ошибках под редкого злоумышленника ценой ясности для всех остальных значит расставлять приоритеты задом наперёд.
У открытой публикации кодов ошибок есть и польза для дисциплины проектирования: она заставляет поддерживать внутреннюю согласованность. Если каждый код ошибки нужно задокументировать с понятным объяснением, становится гораздо труднее накопить груду случайных, пересекающихся условий ошибок, которые полностью понимает только инженер, их написавший. Написание документации к тому же незаметно становится своего рода ревью кода самой обработки ошибок, потому что ошибку, которую трудно ясно объяснить, часто вызывает условие, изначально плохо продуманное.
Сбоям, связанным с квотой, уделено похожее внимание, но через заголовки ответа, а не только через коды ошибок. Каждый ответ содержит ваш лимит квоты, использование, остаток бесплатной квоты, использование по сети, остаток баланса и время сброса, так что запрос, не прошедший из-за квоты, вовсе не загадочный код статуса. Это число, которое вы могли проверить до отправки запроса и которое можно прочитать прямо из ответа на неудачный запрос.
Всё это не избавляет от раздражения из-за неудачного запроса. Это лишь значит, что раздражение должно заканчиваться на документации, реальным ответом, а не продолжаться в очереди поддержки или в гаданиях по старым сообщениям на форумах о том, что мог означать код статуса совсем другого API в похожей на вид ситуации.