Разделить статус, тип и случай
RFC 9457 определяет application/problem+json. Используйте стабильный тип проблемы и понятное описание случая; клиент не должен разбирать переведённую фразу для решения. Поле status, если есть, согласуйте с фактическим HTTP-статусом.
| Статус | Смысл HTTP | Возможное действие |
|---|---|---|
| 400 | Некорректный запрос | Исправить до повтора. |
| 401 | Нет действительных учётных данных | Проверить данные и предусмотренный механизм. |
| 403 | Запрос понят, но отклонён | Проверить права; повтор их не выдаёт. |
| 503 | Сервис временно недоступен | Ограниченно ждать и повторять, если безопасно. |
Предусмотреть пути отказа
- Опишите коды, форматы и ожидаемые действия. Проверьте пустые ответы, не-JSON шлюза, обрывы соединений и тайм-ауты.
- Проверяйте ввод и права на сервере. Обрабатывайте ожидаемые ошибки, не скрывая неизвестные сбои; не выдавайте бизнес-отказ за успех.
- Верните идентификатор корреляции для поддержки. Исключите стеки, внутренние запросы, пароли и токены из публичных ответов.
Повторять только обоснованно
5xx не разрешает бесконечные повторы. Учитывайте контракт, состояние, идемпотентность и срок. Сообщайте дефект минимальным очищенным примером; после исправления проверьте исходный случай и соседние отказы доступа.
Первоисточники
Ошибки API должны направлять действия без утечки информации.
Статус HTTP предоставляет начальную категорию, но клиенту может потребоваться стабильный тип и полезные детали. RFC 9457 описывает общую структуру проблем; он не оправдывает раскрытие внутренних трассировок или конфиденциальных данных.
- Разделяйте постоянный отказ, исправимый ввод и временный сбой.
- Документируйте тип, статус и возможные действия клиента для каждой важной ошибки.
- Проверяйте, что ответы не содержат секретов или ненужных полных полезных нагрузок.
Первичный источник: IETF RFC 9457 — Problem Details for HTTP APIs. Связанный метод: прочитать практическое руководство.
Повторы API: считать полный бюджет времени
Задайте предел вызовов и общий срок.
Вымышленный учебный случай: числа не описывают CIE или клиентов.
Вымышленная модель: четыре вызова до 250 мс, ожидания 100, 200 и 400 мс. Исключены jitter, соединение, очереди и локальная проверка.
- Всего попыток
- 41 + 3
- Сумма ожиданий (мс)
- 700100 + 200 + 400
- Бюджет модели (мс)
- 17004 × 250 + 700
| Шаг | Максимум вызова (мс) | Следующее ожидание (мс) |
|---|---|---|
| Попытка 1 | 250 | 100 |
| Попытка 2 | 250 | 200 |
| Попытка 3 | 250 | 400 |
| Попытка 4 | 250 | 0 |
| Всего | 1000 | 700 |
- Время вызовов1 000
- Сумма ожиданий700
- Общий срок (мс)1 500
Проверки перед выводом
- 1 000 + 700 = 1 700 мс превышают срок 1 500 мс.
- Передавайте общий срок и исключайте дубли эффектов; timeout не доказывает удалённую отмену.
Проверить бюджет повторов
n × T + W × (2^(n−1) − 1)
Связанный метод: прочитать практическое руководство.
Ошибки API: типы, статусы и доказательства
Подробные справочные заметки в этой версии доступны на английском.
Handle an error without parsing its sentence
An API client may receive a translated title, missing member or unfamiliar extension. Preserve decisions based on the documented type and HTTP status, then connect a safe action to the context.
- Compare received status and JSON status without silently replacing either.
- Test absent type, string status instead of a number, and an unknown extension.
- Separate person-facing text, business code and occurrence reference.
Explore problem types and eight fictional responses →
IETF · M. Nottingham, E. Wilde, S. Dalal · RFC 9457 · July 2023 · obsoletes RFC 7807 · §3.1, §3.2, §4.2, §5