[wp-trac] [WordPress Trac] #64256: Add HTTP 500 status code for WordPress critical error messages

[WordPress Trac]

#64256: Add HTTP 500 status code for WordPress critical error messages
----------------------------+-----------------------------
 Reporter:  swissky         |      Owner:  (none)
     Type:  enhancement     |     Status:  new
 Priority:  normal          |  Milestone:  Awaiting Review
Component:  Bootstrap/Load  |    Version:
 Severity:  normal          |   Keywords:
  Focuses:                  |
----------------------------+-----------------------------
 = Summary =
 Ensure HTTP 500 status code is always returned for WordPress critical
 error messages

 = Component =
 Bootstrap/Load (or Site Health)

 = Description =

 Currently, when WordPress displays the critical error message "There has
 been a critical error on this website.", it does not consistently return
 an HTTP status code. While the documentation mentions that fatal errors
 "typically" return HTTP 500, there is no guarantee that monitoring systems
 can reliably detect these errors.

 = Problem =

 Monitoring tools cannot reliably detect WordPress critical errors because:
  * No HTTP status code is guaranteed to be returned
  * The response may appear as HTTP 200 (success) to monitoring systems
  * Critical errors go undetected until manual inspection
  * Existing documentation mentions "typically 500" but doesn't guarantee
 monitoring-friendly behavior

 = Related Tickets =

 Related to ticket #44458 (WSOD - White Screen of Death) which addresses
 error handling improvements.

 = Proposed Solution =

 Ensure that WordPress '''always''' sets HTTP status code 500 when
 displaying critical error messages, regardless of whether a custom `php-
 error.php` template exists or not. This ensures:
  * Monitoring systems can automatically detect critical errors
  * HTTP status codes correctly reflect the error state
  * Standard HTTP error handling works as expected
  * Consistent behavior across all WordPress installations

 = Implementation Options =

 == Option 1: Always set HTTP 500 ==
 Modify `_default_wp_die_handler()` in `wp-includes/functions.php` to
 always set HTTP status code 500 when displaying critical error messages,
 even if headers were already sent.

 == Option 2: Filter/Feature Flag ==
 Add an optional filter `force_500_on_fatal_error` that allows forcing HTTP
 status code 500 for fatal errors, ensuring backward compatibility while
 enabling monitoring-friendly behavior.

 == Option 3: Ensure php-error.php sets status code ==
 Document and ensure that custom `php-error.php` templates should set HTTP
 status codes, and provide a default implementation that always sets 500.

 = Current Behavior =

  * `class-wp-fatal-error-handler.php` sets `'response' => 500` in args
 (line 212)
  * `_default_wp_die_handler()` calls
 `status_header($parsed_args['response'])` (line 3884)
  * However, this only works if `!did_action('admin_head')` and headers
 haven't been sent
  * Custom `php-error.php` templates may not set status codes

 = Testing =

 Tested scenarios:
  * cURL to verify HTTP status code: `curl -I https://example.com/test-
 fatal-error.php`
  * Browser developer tools to check response headers
  * Monitoring systems to verify error detection
  * Cases where headers were already sent

 = Backward Compatibility =

 This change should be backward compatible:
  * Only affects HTTP status codes, not error messages
  * Doesn't change existing error handling logic
  * Can be implemented as opt-in via filter if needed

 = Use Case =

 Monitoring systems rely on HTTP status codes to detect server errors.
 Currently, WordPress critical errors may not return HTTP 500, causing:
  * False negatives in monitoring alerts
  * Delayed detection of critical issues
  * Inconsistent error reporting

 = References =

  * WordPress documentation mentions fatal errors "typically" return HTTP
 500
  * Related to ticket #44458 (WSOD improvements)
  * Monitoring systems require reliable HTTP status codes for error
 detection

-- 
Ticket URL: <https://core.trac.wordpress.org/ticket/64256>
WordPress Trac <https://core.trac.wordpress.org/>
WordPress publishing platform