Найти в Дзене
60 подписчиков

Как документировать ошибки в API?


Сегодня про то, что часто пропускают и не особо продумывают в современных компаниях - API ошибки.

Типичный кейс, как и с НФТ, что люди просто делают ctrl-c + ctrl-v.

Однако, это классно работает, когда вы занимаетесь доработкой готовой системы, а что делать, если у вас что-то новое? Как быть?

Прежде, чем ответить на этот вопрос, давайте скажу, почему важно думать про ошибки:

✔️ Легче анализировать возникающие проблемы,
✔️ Это юзер френдли и пользователи и разработчики вам за это скажут только спасибо.

Как описать ошибки, чтобы это было красиво и правильно?

1️⃣ используем стандартизированные коды HTTP

✔️ 400 Bad Request — клиент что-то напутал;
✔️ 401 Unauthorized — нужна аутентификация;
✔️ 404 Not Found — не нашли, что искали;
✔️ 500 Internal Server Error — что-то сломалось на сервере.

➖➖➖

2️⃣ добавляем дополнительную информацию в ответ

Краткость, конечно, сестра таланта, но зачастую код-статуса не всегда информативен и нужна пояснительная бригада, поэтому в ответ можно добавить:

✔️ Уникальный ID ошибки (пусть коллеги ищут её в логах, а не в панике). Только не добавляйте это наружу;
✔️Чёткое описание проблемы;
✔️ Подсказку, как её исправить.
Если такое возможно 😉

Например,

{
"status": 400,
"error": "invalid_request",
"message": "Поле 'email' обязательно.",
"details": [
{
"field": "email",
"issue": "missing"
}
],
"timestamp": "2025-01-08T14:45:00Z",
"trace_id": "abc123xyz"
}

➖➖➖

3️⃣ Придерживайтесь правил, которые приняты в компании.

Формат ошибок должен быть единым для всех эндпоинтов и желательно для всех API. Это позволит поддерживать универсальность обработки этого добра

➖➖➖

Надеюсь с этим понятно, но, чтобы было нагляднее, как можно сделать, то вот парочка примеров от известных компаний:

✔️Google API: они добавляют у себя детальную информацию об ошибке, код и статус.

{
"error": {
"code": 404,
"message": "Requested entity was not found.",
"status": "NOT_FOUND"
}
}

➖➖➖

✔️ Stripe: они разделяют ошибки по типам и добавляют пояснение.

{
"error": {
"type": "invalid_request_error",
"message": "Missing required param: email"
}
}

➖➖➖

✔️ GitHub: эти ребята немного борщат на мой взгляд, но подход интересный. Они добавляют ошибки с подсказками и ссылками на документацию.

{
"message": "Validation Failed",
"errors": [
{
"resource": "Issue",
"field": "title",
"code": "missing_field"
}
],
"documentation_url": "https://docs.github.com/rest"
}

➖➖➖

На этом пожалуй все. Делитесь, как у вас оформляют ошибки в компании?
2 минуты