Как документировать ошибки в 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" }

➖➖➖

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

t.me

ПРО АНАЛИТИКА

#аналитика #системнаяаналитика #it #api