Большинство программных систем написаны на одном из популярных языков программирования и имеют стандартные библиотеки для работы по протоколу HTTP. Поэтому естественным образом возник и стал широко применяться подход проектирования API поверх HTTP.
Реализация API поверх HTTP не приводит к существенным дополнительным задержкам, помимо уже существующих и возникающих между аппаратным железом и интегрируемыми системами. А поскольку HTTP — протокол текстовый, это упрощает разработку и отладку небольших интегрируемых систем.
Серверная часть сообщает об ошибке двумя способами: при помощи кода состояния HTTP и в рамках проектируемого API.
Сервер может записывать ответы в заголовки, но наиболее распространённый вариант — внутри сообщения, структурированного в формате JSON.
Классы кодов состояния HTTP
Это способ сервера сообщить пользователю о статусе обработки API-запроса. Данные отображаются в виде трёхзначных чисел, где первая цифра обобщает категорию, а остальные две показывают точный характер ошибки.
Краткий обзор классов кодов состояния HTTP:
- 1xx. Информационный — передаёт информацию на уровне протокола передачи.
- 2xx. Успех — коды от 200 до 299 включительно означают, что вызов API прошёл успешно.
- 3хх. Перенаправление.
- 4xx. Ошибка клиента — сам API-запрос такой, что его нельзя обработать.
- 5xx. Ошибка сервера — во время обработки запроса что-то помешало выполнению задачи.
Распространённые ошибки API
301, Moved Permanently
Появление нового адреса у ресурса, который сервер передаёт в заголовке Location. Клиентское приложение должно автоматически обрабатывать этот тип перенаправления и обновлять URL для всех последующих запросов к данному ресурсу.
304, Not Modified
Данный статус применяется для оптимизации кеширования. Сервер возвращает его, когда клиентский запрос содержит заголовки — например, If-None-Match, который говорит о наличии у клиента актуальной версии данных. Это позволяет избежать передачи дублирующей информации и экономит ресурсы.
400, Bad request error
Сервер не смог проанализировать запрос из-за ввода некорректного URL-адреса или неправильно составленного запроса. Если синтаксически всё оформлено верно и данные введены правильно, ищите ошибки в самом приложении.
401, Bad request error
Ошибка API при аутентификации пользователя, вводе неправильного имени и пароля, а также при отсутствии права доступа. Если данные введены правильно, но вы всё ещё получаете сообщение об ошибке, обратитесь в техническую поддержку поставщика API.
403, Forbidden
Сервер отклоняет запрос из-за недостаточных прав доступа, даже если учётные данные валидны. Это означает, что текущий пользователь или приложение не имеют разрешения на выполнение данной операции. Требуется пересмотр политики авторизации.
404, Not Found
Запрашиваемый ресурс отсутствует на сервере. Возможные причины: неверный URL, удалённый или перемещённый ресурс. Рекомендуется проверить корректность endpoint и параметров запроса.
422, Unprocessable Entity
Запрос синтаксически корректен, но содержит семантические ошибки. Например: неверный формат данных, нарушение бизнес-логики или недостаточность параметров. Часто возвращается при валидации входных данных в REST API.
429, Too Many Requests
Превышено ограничение на частоту запросов. Для решения рекомендуется:
- Реализовать экспоненциальную задержку между повторами
- Оптимизировать частоту обращений к API
- Кешировать результаты запросов, где это возможно
500, Internal Server Error
Общая ошибка серверной части, не позволяющая обработать корректный запрос. Может быть вызвана ошибками в коде, проблемами зависимостей или конфигурации. Рекомендуется проверить логи сервера и обратиться к разработчикам API.
502, Bad Gateway
Сервер, работающий в роли шлюза или прокси, получил некорректный ответ от вышестоящего сервера. Типичные причины: проблемы с сетевым соединением, недоступность upstream-сервисов или их некорректная конфигурация.
503, Service Unavailable
Сервер временно не может обрабатывать запросы из-за перегрузки или технического обслуживания. В заголовке Retry-After может быть указано рекомендованное время повтора запроса.
504, Gateway Timeout
Сервер в роли шлюза не получил ответ от вышестоящего сервера в установленное время. Чаще всего это связано с проблемами производительности или доступности upstream-сервисов.
Об API поверх HTTP
Описывающие HTTP стандарты дают разработчикам достаточно свободы для проектирования API поверх протокола. Например, сервисы телефонии и SIP-провайдеры часто предоставляют HTTP API для управления номерами, звонками и переадресациями, что позволяет легко встраивать их в корпоративные системы и автоматизировать процессы.
Пример.
К МТС Exolve подключилась компания, которая организовала внутрикорпоративную техническую поддержку. Процесс работы был автоматизирован и включал блокировку уволившихся работников, получение выписки по звонкам и настройку переадресации с учётом загрузки сотрудников. Для выполнения задач использовались Numbering API и Voice API, которые спроектированы поверх HTTP.
Любая компания может работать с МТС Exolve подобным образом, реализовав поддержку этого API у себя.
Популярные примеры API, реализованных поверх HTTP, включают как международные, так и ключевые российские сервисы:
- API ЮKassa или Тинькофф Кассы для обработки платежей
- API СберБизнесАПИ или API Тинькофф Бизнеса
- API Госуслуг для работы с единой системой идентификации и аутентификации
- API VK для интеграции с социальной сетью «ВКонтакте»
- API Яндекс Облака или S3 Cloud для облачного хранения и вычислений
Заключение
Ошибки API могут быть вызваны множеством факторов. Разработчику важно не только понимать их значение, но и знать инструменты для отладки: используйте cURL, Postman, встроенные средства разработчика в IDE. Ведите логирование всех исходящих и входящих запросов с уникальными идентификаторами для отслеживания цепочек вызовов.
Регулярно отслеживайте метрики вашего API с помощью APM-систем, чтобы заблаговременно обнаруживать проблемы, такие как рост количества ошибок 5хх или увеличение времени ответа.
Всегда реализуйте на стороне клиента обработку частых ошибок — например, повторные попытки для 5xx и 429 с помощью алгоритма exponential backoff.
Если ошибки API обрабатываются должным образом, их можно быстро устранить с минимальными последствиями для клиентов. Использование современных инструментов и стандартов, таких как OpenAPI для документирования, значительно упрощает жизнь как разработчикам API, так и его потребителям.
