REST status codes

Status codes сообщают класс результата клиентам, прокси и retry-логике. Используйте минимально точный код; детали — в теле ответа.

| Code | Когда использовать | |------|-------------------| | 200 OK | Успешный GET, PUT, PATCH с телом | | 201 Created | POST создал resource; укажите Location | | 204 No Content | Успешный DELETE или update без тела | | 400 Bad Request | Битый синтаксис, неизвестные поля, невалидный JSON | | 401 Unauthorized | Нет или неверная аутентификация | | 403 Forbidden | Аутентифицирован, но нет прав | | 404 Not Found | Resource отсутствует или скрыт (политика) | | 409 Conflict | Конфликт состояния (дубликат, version mismatch) | | 422 Unprocessable Entity | Валидный JSON, но бизнес-валидация не прошла | | 429 Too Many Requests | Rate limit; отправьте Retry-After | | 500 Internal Server Error | Неожиданная ошибка сервера | | 503 Service Unavailable | Перегрузка или dependency недоступен; Retry-After |

					HTTP/1.1 201 Created
Location: /orders/7f3a2c
Content-Type: application/json

{"id":"7f3a2c","status":"pending"}
				

					HTTP/1.1 409 Conflict
Content-Type: application/problem+json

{"type":"order/already-shipped","title":"Cannot cancel shipped order"}
				

На интервью: различайте 401 vs 403, 400 vs 422, когда 404 скрывает существование, и почему 500 не должен раскрывать stack traces.

Типовые ошибки: 200 с ошибкой в теле, 404 для auth непоследовательно, 500 для validation errors, отсутствие Retry-After на 429/503.

Компромисс: детальные коды против простоты клиента — в любом случае документируйте стабильный каталог ошибок.

Чеклист:

• Код согласован с retryability (4xx обычно нет, 5xx/429 — возможно).
• 201 + Location при create.
• Последовательная семантика 401/403.
• Детали проблемы в теле, не только в status.