Status Code Checking

This document explains the methods available for checking HTTP response status codes and conditionally throwing exceptions based on response status. The Response class provides both range-based status checking (e.g., "is this a 2xx success?") and specific status code checking (e.g., "is this exactly 404?").

For information about accessing response data, see Data Extraction and Transformation. For information about exception handling, see Error Handling and Exceptions.

---

Overview

The HTTP client provides two complementary approaches to status code validation:

1. Range-based checking - Methods that check if a status code falls within standard HTTP ranges (2xx success, 3xx redirect, 4xx client error, 5xx server error)
2. Specific status checking - Methods that check for exact status codes (200 OK, 404 Not Found, etc.)

Both approaches are provided by the Response class through its use of the DeterminesStatusCode trait.

Sources: src/Response.php1-501 src/Concerns/DeterminesStatusCode.php1-145

---

Status Code Architecture

Diagram: Response Class Status Checking Architecture

The Response class combines range-based methods (defined directly in the class) with specific status code methods (provided by the DeterminesStatusCode trait). All status checking ultimately relies on the status() method, which retrieves the code from the underlying PSR-7 ResponseInterface.

Sources: src/Response.php25-29 src/Response.php173-176 src/Concerns/DeterminesStatusCode.php1-145

---

Basic Status Retrieval

The status() method returns the HTTP status code as an integer:

The reason() method returns the reason phrase associated with the status code:

Implementation Details:

Method	Return Type	Description	Source
status()	int	Returns the HTTP status code from the PSR-7 response	src/Response.php173-176
reason()	string	Returns the reason phrase (e.g., "OK", "Not Found")	src/Response.php179-184

Sources: src/Response.php173-184

---

Range-Based Status Checking

These methods check whether a status code falls within standard HTTP status code ranges:

Diagram: Range-Based Status Code Decision Flow

Success and Failure Detection

Method	Status Range	Returns true when	Source
successful()	200-299	Response indicates success	src/Response.php197-200
failed()	400+	Response indicates client or server error	src/Response.php213-216
redirect()	300-399	Response is a redirect	src/Response.php205-208
clientError()	400-499	Response is a client error	src/Response.php221-224
serverError()	500+	Response is a server error	src/Response.php229-232

Usage Examples

Implementation Note: The failed() method returns true when either serverError() or clientError() returns true, as shown in src/Response.php213-216

Sources: src/Response.php197-232

---

Specific Status Code Checking

The DeterminesStatusCode trait provides methods for checking specific HTTP status codes. These methods are useful when you need to handle particular status codes differently.

Success Status Codes (2xx)

Method	Status Code	Description	Source
ok()	200	Standard success response	src/Concerns/DeterminesStatusCode.php12-15
created()	201	Resource successfully created	src/Concerns/DeterminesStatusCode.php20-23
accepted()	202	Request accepted for processing	src/Concerns/DeterminesStatusCode.php28-31
noContent()	204 (default)	Success with no response body	src/Concerns/DeterminesStatusCode.php36-39

The noContent() method accepts an optional status code parameter and also verifies that the response body is empty:

Redirection Status Codes (3xx)

Method	Status Code	Description	Source
movedPermanently()	301	Resource permanently moved	src/Concerns/DeterminesStatusCode.php44-47
found()	302	Resource temporarily moved	src/Concerns/DeterminesStatusCode.php52-55
notModified()	304	Resource not modified since last request	src/Concerns/DeterminesStatusCode.php60-63

Client Error Status Codes (4xx)

Method	Status Code	Description	Source
badRequest()	400	Malformed request syntax	src/Concerns/DeterminesStatusCode.php68-71
unauthorized()	401	Authentication required	src/Concerns/DeterminesStatusCode.php76-79
paymentRequired()	402	Payment required	src/Concerns/DeterminesStatusCode.php84-87
forbidden()	403	Server refuses to fulfill request	src/Concerns/DeterminesStatusCode.php92-95
notFound()	404	Resource not found	src/Concerns/DeterminesStatusCode.php100-103
requestTimeout()	408	Request took too long	src/Concerns/DeterminesStatusCode.php108-111
conflict()	409	Request conflicts with current state	src/Concerns/DeterminesStatusCode.php116-119
unprocessableContent()	422	Validation failed	src/Concerns/DeterminesStatusCode.php124-127
unprocessableEntity()	422	Alias for unprocessableContent()	src/Concerns/DeterminesStatusCode.php132-135
tooManyRequests()	429	Rate limit exceeded	src/Concerns/DeterminesStatusCode.php140-143

Usage Examples

Sources: src/Concerns/DeterminesStatusCode.php1-145

---

Status Code Checking Decision Flow

Diagram: Status Code Checking Decision Flow

Sources: src/Response.php197-232 src/Concerns/DeterminesStatusCode.php1-145

---

Conditional Exception Throwing

The Response class provides several methods for conditionally throwing RequestException based on status codes:

Diagram: Exception Throwing Methods Decision Tree

Exception Throwing Methods

Method	Throws When	Parameters	Source
throw()	Response has failed (4xx or 5xx)	Optional callback	src/Response.php297-310
throwIf()	Condition is true AND response failed	bool|Closure $condition, optional callback	src/Response.php317-320
throwIfStatus()	Status matches given code or callback returns true	callable|int $statusCode	src/Response.php329-337
throwUnlessStatus()	Status does NOT match given code or callback returns false	callable|int $statusCode	src/Response.php346-353
throwIfClientError()	Response is a client error (4xx)	None	src/Response.php360-363
throwIfServerError()	Response is a server error (5xx)	None	src/Response.php370-373

Usage Examples

Basic Exception Throwing:

Conditional Throwing:

Status-Specific Throwing:

Error Category Throwing:

With Error Callback:

Method Chaining

All throw methods return $this when they don't throw, allowing for fluent method chaining:

Sources: src/Response.php297-373

---

Error Callbacks

The onError() method provides a way to execute a callback when a response has failed, without throwing an exception:

The onError() method only invokes the callback if failed() returns true (status >= 400). It returns $this for method chaining.

Implementation: src/Response.php237-244

Sources: src/Response.php237-244

---

Creating Exceptions Without Throwing

The toException() method creates a RequestException from the response without throwing it:

This method returns null if the response was successful.

Implementation: src/Response.php283-290

Sources: src/Response.php283-290

---

Complete Status Checking Workflow

Diagram: Complete Status Checking Workflow

Sources: src/Response.php173-373 src/Concerns/DeterminesStatusCode.php1-145

---

Summary

The HTTP client provides comprehensive status code checking through two complementary systems:

1. Range-based methods in the Response class for broad categorization (2xx, 3xx, 4xx, 5xx)
2. Specific status methods from the DeterminesStatusCode trait for exact status codes

These methods integrate seamlessly with exception throwing capabilities, allowing developers to:

• Check status codes without throwing exceptions
• Conditionally throw exceptions based on various criteria
• Execute callbacks on errors without disrupting flow
• Chain multiple status checks in fluent syntax

All methods return consistent types and support method chaining for ergonomic API design.

Sources: src/Response.php1-501 src/Concerns/DeterminesStatusCode.php1-145