Ответ с ошибкой не сноска к API, а часть контракта, на который каждая интеграция опирается так же, как на успешный ответ. Мы стандартизировали формат ошибок во всех собственных эндпоинтах My Geocode, так что сбой выглядит одинаково независимо от того, какая часть API его вызвала.
Не важно, завершился ли запрос ошибкой из-за отсутствующего параметра, неверного ключа, исчерпанной квоты или некорректной координаты: ответ имеет одну предсказуемую структуру. Благодаря этому код обработки ошибок, написанный один раз для одного эндпоинта, так же работает со всеми остальными собственными эндпоинтами, без отдельной логики обработки для каждого.
Отдельно стоит упомянуть ошибки, связанные с квотой, поскольку активная интеграция сталкивается с ними чаще всего. Когда запрос превысил бы квоту ключа или сети, ответ ясно об этом говорит, а заголовки квоты, которые и так есть в каждом ответе, X-Quota-Limit, X-Quota-Used, X-Quota-Free-Remaining и остальные, точно показывают, сколько запаса было до неудачного запроса. Такое сочетание позволяет клиенту по одному только ответу отличить проблему с квотой от проблемы с аутентификацией или некорректного запроса, ничего не угадывая.
Совместимые хосты намеренно являются исключением из этой стандартизации, и на то есть веская причина. Их единственная задача состоит в том, чтобы в точности воспроизводить формат запросов и ответов другого провайдера, в том числе то, как выглядят ошибки. Запрос в формате Bing Maps REST Services, завершившийся ошибкой, всё равно получает ошибку в собственном формате Bing, потому что точное соответствие этому формату, при успехе или неудаче, и есть весь смысл совместимого хоста. Стандартизация ошибок там сломала бы ту самую совместимость, ради которой хост существует.
Для всего, что построено на наших собственных эндпоинтах, этот более понятный формат должен заметно упростить написание и сопровождение обработки ошибок. Одна процедура разбора, один набор ожидаемых полей и одинаковое поведение во всех эндпоинтах: /v1/forward, /v1/reverse, /v1/ip, /v1/timezone, /v1/elevation, /v1/autocomplete и /v1/postcode.
Полная документация по формату ошибок, включая названия полей и типичные причины, доступна на странице /docs/errors/. Если в вашей интеграции сейчас есть отдельные ветки обработки ошибок для разных собственных эндпоинтов, это хороший момент, чтобы свести их к одной.