API Error Response

An API error response is a response returned by the server when it cannot successfully complete the requested operation.

For example:

404 Not Found

{
    "success": false,
    "message": "Student not found"
}

A mobile application needs to know why an API request failed. A clear error response makes it easier to handle problems correctly.

For example, the application may need to show:

• Invalid login details
• Student not found
• Required field missing
• Unauthorized request
• Server error

A simple API error response can contain a success flag and message.

{
    "success": false,
    "message": "Student not found"
}

The false value indicates that the operation was not successful.

An API should also use an appropriate HTTP status code.

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "success": false,
    "message": "Student not found"
}

The status code and JSON body work together to describe the error.

The 400 Bad Request status can be used when the server cannot process the request because the request is invalid.

HTTP/1.1 400 Bad Request

{
    "success": false,
    "message": "Invalid request"
}

The 401 Unauthorized status is commonly used when authentication credentials are missing or invalid.

HTTP/1.1 401 Unauthorized

{
    "success": false,
    "message": "Authentication required"
}

This is commonly encountered when working with token-based authentication.

The 403 Forbidden status indicates that the server understood the request but refuses to authorize the requested operation.

HTTP/1.1 403 Forbidden

{
    "success": false,
    "message": "Access denied"
}

This can be useful when implementing role-based authorization.

The 404 Not Found status can be returned when a requested resource does not exist.

HTTP/1.1 404 Not Found

{
    "success": false,
    "message": "Student not found"
}

For example, a request for /api/students/1000 may return 404 if student 1000 does not exist.

The 405 Method Not Allowed status can be used when the HTTP method is not supported by an endpoint.

HTTP/1.1 405 Method Not Allowed

{
    "success": false,
    "message": "Method not allowed"
}

A 422 Unprocessable Content response can be used when the request is syntactically valid but contains data that cannot be accepted by the application.

HTTP/1.1 422 Unprocessable Content

{
    "success": false,
    "message": "Validation failed"
}

The 500 Internal Server Error status indicates that the server encountered an unexpected condition while processing the request.

HTTP/1.1 500 Internal Server Error

{
    "success": false,
    "message": "Internal server error"
}

Production APIs should avoid exposing sensitive server details in error responses.

A validation response can contain details about individual fields.

{
    "success": false,
    "message": "Validation failed",
    "errors": {
        "name": "Name is required",
        "email": "Email is invalid"
    }
}

This structure is useful for displaying field-specific messages in a mobile form.

An API may need to return more than one validation error.

{
    "success": false,
    "message": "Please correct the errors",
    "errors": {
        "name": "Name is required",
        "email": "Email is required",
        "mobile": "Mobile number is invalid"
    }
}

An application can also include an application-specific error code.

{
    "success": false,
    "code": "STUDENT_NOT_FOUND",
    "message": "Student not found"
}

The application-specific code can help the mobile application handle known error conditions.

Additional details can be included when they are useful and safe to expose.

{
    "success": false,
    "message": "Unable to create student",
    "details": "Email already exists"
}

Sensitive internal information such as database credentials or stack traces should not be returned to clients.

PHP can create a JSON error response using http_response_code() and json_encode().

http_response_code(404);

header(
    "Content-Type: application/json"
);

echo json_encode([
    "success" => false,
    "message" => "Student not found"
]);

exit;

A PHP API can validate required fields before processing a request.

if (empty($name)) {

    http_response_code(400);

    echo json_encode([
        "success" => false,
        "message" => "Name is required"
    ]);

    exit;
}

If a database operation fails unexpectedly, the API can return a server error response.

http_response_code(500);

echo json_encode([
    "success" => false,
    "message" => "Unable to process request"
]);

exit;

Detailed database errors should normally be logged on the server rather than exposed to the mobile application.

React Native can check the HTTP response before processing the result.

const response = await fetch(
    "https://example.com/api/students/100"
);

const result = await response.json();

if (!response.ok) {

    console.log(result.message);

} else {

    console.log(result.data);

}

The response.ok property indicates whether the HTTP status is in the successful range.

Axios provides an error object when an HTTP request fails.

try {

    const response = await axios.get(
        "https://example.com/api/students/100"
    );

    console.log(response.data);

} catch (error) {

    console.log(
        error.response?.data
    );

}

The server's JSON error response can be accessed through the Axios error response data when available.

The error message returned by the API can be displayed to the user.

if (!response.ok) {

    const result =
        await response.json();

    Alert.alert(
        "Error",
        result.message
    );

    return;
}

This allows the application to show a useful message instead of a generic failure message.

TypeScript can describe the structure of an API error.

interface ApiError {
    success: boolean;
    message: string;
    code?: string;
    errors?: {
        [key: string]: string;
    };
}

This makes error handling more predictable in a TypeScript React Native application.

An API can return a clear error when authentication fails.

HTTP/1.1 401 Unauthorized

{
    "success": false,
    "message": "Invalid credentials"
}

This can be used by a login screen to inform the user that the provided credentials were not accepted.

• Returning the wrong HTTP status code.
• Returning HTML instead of JSON from a JSON API.
• Using unclear error messages.
• Exposing database errors to users.
• Exposing passwords or tokens in error responses.
• Returning inconsistent error structures.
• Not validating input.
• Not handling errors in the mobile application.

A practical error response can contain a small set of consistent properties.

{
    "success": false,
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "errors": {
        "email": "Email is required"
    }
}

Postman is useful for testing API errors before connecting the API to a React Native application.

1. Open Postman.
2. Enter the API URL.
3. Use an invalid ID or invalid data.
4. Send the request.
5. Check the HTTP status code.
6. Check the JSON response.
7. Verify that the error message is clear.

React Native
      ↓
API Request
      ↓
PHP REST API
      ↓
Validate Request
      ↓
Error Found
      ↓
HTTP Status Code
      ↓
JSON Error Response
      ↓
React Native
      ↓
Display Error Message

Suppose the mobile application requests a student that does not exist.

GET /api/students/999

HTTP/1.1 404 Not Found
Content-Type: application/json

{
    "success": false,
    "code": "STUDENT_NOT_FOUND",
    "message": "Student not found"
}

React Native can check the status and display the message:

if (!response.ok) {

    const error =
        await response.json();

    Alert.alert(
        "Error",
        error.message
    );
}

A good REST API should return meaningful errors using appropriate HTTP status codes and a consistent JSON response structure.

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "success": false,
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "errors": {
        "name": "Name is required",
        "email": "Email is invalid"
    }
}

The React Native application can read this response, determine what went wrong, and display an appropriate message to the user.

Remember the basic pattern:

HTTP Status Code
       +
JSON Error Response
       ↓
Clear Error Handling