За что отвечает группа кодов ответа 500

# HTTP статус-коды 5xx (500+)

Определение

Коды ответов 5xx (500-599) указывают на ошибки на стороне сервера (Server Error). Это означает, что сервер получил валидный запрос, но не смог его обработать из-за собственной ошибки.

Ключевое различие: 4xx vs 5xx

4xx ошибки (Client Error)       vs    5xx ошибки (Server Error)
─────────────────────────────────────────────────────────────────
Вина клиента                          Вина сервера
Неправильный запрос                   Ошибка в коде сервера
Клиент может исправить запрос        Клиент ничего не может сделать
Примеры:                              Примеры:
- 400 Bad Request                     - 500 Internal Server Error
- 401 Unauthorized                    - 502 Bad Gateway
- 403 Forbidden                       - 503 Service Unavailable
- 404 Not Found                       - 504 Gateway Timeout

Основные коды 5xx

1. 500 Internal Server Error

Общая ошибка сервера — что-то пошло не так при обработке запроса.

// Пример: необработанное исключение
@RestController
public class OrderController {
    
    @GetMapping("/orders/{id}")
    public Order getOrder(@PathVariable Long id) {
        return orderService.findById(id);  // ❌ NullPointerException!
        // Статус: 500 Internal Server Error
    }
}

// В логах:
// java.lang.NullPointerException: Order not found

Когда возвращать:

@ExceptionHandler(Exception.class)
public ResponseEntity<ErrorResponse> handleException(Exception e) {
    logger.error("Internal server error", e);
    return ResponseEntity
        .status(HttpStatus.INTERNAL_SERVER_ERROR)
        .body(new ErrorResponse("An error occurred"));
}

2. 501 Not Implemented

Сервер не поддерживает требуемую функцию.

// Пример: метод HTTP не реализован
@RestController
public class PaymentController {
    
    @PostMapping("/payments")
    public Payment createPayment(@RequestBody PaymentRequest req) {
        return paymentService.process(req);
    }
    
    // DELETE не реализован
    // Если клиент отправит DELETE /payments/123
    // Статус: 501 Not Implemented
}

3. 502 Bad Gateway

Сервер получил неправильный ответ от upstream сервера (reverse proxy, load balancer, микросервис).

Клиент ──> Load Balancer ──X──> Backend Server
                  ↓
            502 Bad Gateway
            (Backend не ответил или вернул мусор)

Сценарий в микросервисной архитектуре:

// Service A вызывает Service B через Nginx
@RestController
public class OrderController {
    @Autowired
    private RestTemplate restTemplate;
    
    @GetMapping("/orders/{id}")
    public Order getOrder(@PathVariable Long id) {
        try {
            // Вызов Service B через Nginx
            ResponseEntity<Order> response = restTemplate.getForEntity(
                "http://service-b/api/orders/" + id,
                Order.class
            );
            
            // Если Service B упала или вернула мусор
            // Nginx вернёт 502 Bad Gateway
            
            return response.getBody();
        } catch (RestClientException e) {
            // Вернём 502
            return ResponseEntity
                .status(HttpStatus.BAD_GATEWAY)
                .build();
        }
    }
}

4. 503 Service Unavailable

Сервер временно недоступен (перезагрузка, обслуживание, перегруз).

@RestController
public class HealthController {
    @Autowired
    private DatabaseService db;
    
    @GetMapping("/health")
    public ResponseEntity<?> health() {
        // Если БД упала
        if (!db.isHealthy()) {
            return ResponseEntity
                .status(HttpStatus.SERVICE_UNAVAILABLE)
                .body("Service is temporarily unavailable");
        }
        return ResponseEntity.ok("OK");
    }
}

Когда возвращать:

• БД недоступна
• Сервис на обслуживании
• Слишком много запросов (rate limiting)
• Критические зависимости упали

5. 504 Gateway Timeout

Upstream сервер не ответил в отведённое время.

// Service A ждёт Service B слишком долго
@RestController
public class SearchController {
    @Autowired
    private RestTemplate restTemplate;
    
    @GetMapping("/search")
    public SearchResult search(@RequestParam String query) {
        try {
            // Service B обрабатывает 30 секунд, а timeout 10 сек
            ResponseEntity<SearchResult> response = restTemplate
                .getForEntity(
                    "http://service-b/api/search?q=" + query,
                    SearchResult.class
                );  // ReadTimeout: 504 Gateway Timeout
            
            return response.getBody();
        } catch (ResourceAccessException e) {
            // Nginx вернул 504
            return ResponseEntity
                .status(HttpStatus.GATEWAY_TIMEOUT)
                .build();
        }
    }
}

Таблица основных 5xx кодов

Код  Название                     Причина
───────────────────────────────────────────────────────────────
500  Internal Server Error         Неизвестная ошибка на сервере
501  Not Implemented               Функция не реализована
502  Bad Gateway                   Неправильный ответ от upstream
503  Service Unavailable           Сервер временно недоступен
504  Gateway Timeout               Timeout от upstream сервера
505  HTTP Version Not Supported    HTTP версия не поддерживается

Как обрабатывать 5xx ошибки (для клиента)

// В API клиенте
public class ApiClient {
    private RestTemplate restTemplate;
    private static final int MAX_RETRIES = 3;
    
    public <T> T getWithRetry(String url, Class<T> responseType) 
            throws InterruptedException {
        
        for (int attempt = 1; attempt <= MAX_RETRIES; attempt++) {
            try {
                return restTemplate.getForObject(url, responseType);
            } catch (HttpServerErrorException e) {
                // 5xx ошибка
                if (e.getStatusCode().value() >= 500) {
                    if (attempt < MAX_RETRIES) {
                        // Экспоненциальная задержка перед retry
                        long delay = (long) Math.pow(2, attempt - 1) * 1000;
                        Thread.sleep(delay);
                        continue;
                    }
                }
                throw e;
            }
        }
        
        throw new RuntimeException("Failed after " + MAX_RETRIES + " attempts");
    }
}

Логирование 5xx ошибок

@RestControllerAdvice
public class GlobalExceptionHandler {
    
    @ExceptionHandler(Exception.class)
    public ResponseEntity<ErrorResponse> handleException(Exception e) {
        // 5xx ошибки ВСЕГДА логируем
        logger.error("Internal server error occurred", e);
        
        // Используем request ID для трейсировки
        String requestId = UUID.randomUUID().toString();
        
        return ResponseEntity
            .status(HttpStatus.INTERNAL_SERVER_ERROR)
            .body(new ErrorResponse(
                "Internal server error occurred",
                "Request ID: " + requestId  // Помощь для debugging
            ));
    }
    
    @ExceptionHandler(ServiceUnavailableException.class)
    public ResponseEntity<ErrorResponse> handleServiceUnavailable(Exception e) {
        logger.warn("Service temporarily unavailable", e);
        
        return ResponseEntity
            .status(HttpStatus.SERVICE_UNAVAILABLE)
            .body(new ErrorResponse("Please try again later"));
    }
}

На собеседовании

Ответь так:

"Коды ответов 5xx (500-599) указывают на ошибки на стороне сервера.

Главные коды:

• 500 Internal Server Error — неизвестная ошибка при обработке запроса
• 502 Bad Gateway — неправильный ответ от upstream сервера/микросервиса
• 503 Service Unavailable — сервер временно недоступен
• 504 Gateway Timeout — upstream сервер не ответил в отведённое время

Ключевое отличие: в отличие от 4xx (вина клиента), 5xx — это вина сервера. Клиент не может сам исправить проблему, может только retry."

Выводы

• ✅ 5xx = Server Error — вина сервера
• ✅ 500 — общая/неизвестная ошибка
• ✅ 502 — upstream сервер вернул мусор
• ✅ 503 — сервер временно недоступен
• ✅ 504 — timeout от upstream сервера
• 📊 Мониторить 5xx — это индикатор проблем с production
• 🔧 Логировать с деталями — для быстрого debugging