Skip to main content

​
Error Response Format

All error responses in the Blackjack API follow a consistent JSON structure defined by the ErrorResponse class: 
{
  "timestamp": "2024-03-06T10:15:30.123Z",
  "status": 404,
  "code": "GAME_NOT_FOUND",
  "message": "Game not found: abc123",
  "path": "/api/v1/games/abc123"
}

​
Response Fields

FieldTypeDescription
timestampstring (ISO 8601)The exact time when the error occurred
statusintegerHTTP status code
codestringMachine-readable error code for programmatic handling
messagestringHuman-readable error message with details
pathstringThe API endpoint path that generated the error

​
Global Exception Handler

The API uses a centralized exception handling mechanism through the GlobalExceptionHandler class, which intercepts exceptions and converts them into standardized error responses. 
@RestControllerAdvice
@Order(-2)
public class GlobalExceptionHandler {
    // Exception handlers...
}
This handler catches domain exceptions and framework validation errors, ensuring consistent error responses across all endpoints.

​
HTTP Status Codes

The Blackjack API uses standard HTTP status codes to indicate the success or failure of requests:

​
Success Codes

  • 200 OK - Request succeeded
  • 201 Created - New resource created successfully

​
Client Error Codes

  • 400 Bad Request - Invalid input, validation error, or bad request format
  • 404 Not Found - Requested resource (game or player) not found
  • 409 Conflict - Invalid move or operation not allowed in current state

​
Server Error Codes

  • 500 Internal Server Error - Unexpected server error

​
Error Response Examples

​
Resource Not Found (404)

When requesting a game or player that doesn’t exist: 
{
  "timestamp": "2024-03-06T10:15:30.123Z",
  "status": 404,
  "code": "GAME_NOT_FOUND",
  "message": "Game not found: abc123",
  "path": "/api/v1/games/abc123"
}

​
Validation Error (400)

When providing invalid input data: 
{
  "timestamp": "2024-03-06T10:15:30.123Z",
  "status": 400,
  "code": "INVALID_PLAYER_NAME",
  "message": "PlayerName too long (max 30)",
  "path": "/api/v1/players/123/name"
}

​
Business Logic Error (409)

When attempting an invalid game move: 
{
  "timestamp": "2024-03-06T10:15:30.123Z",
  "status": 409,
  "code": "INVALID_MOVE",
  "message": "Game is not in progress",
  "path": "/api/v1/games/abc123/move"
}

​
Internal Server Error (500)

When an unexpected error occurs: 
{
  "timestamp": "2024-03-06T10:15:30.123Z",
  "status": 500,
  "code": "INTERNAL_ERROR",
  "message": "Unexpected error",
  "path": "/api/v1/games/abc123"
}

​
Error Handling Best Practices

​
Client Implementation

When integrating with the Blackjack API, implement error handling based on:
  1. HTTP Status Code - For high-level error categorization
  2. Error Code - For specific error type handling
  3. Message - For logging and user-friendly error display

​
Example Error Handling

try {
  const response = await fetch('/api/v1/games/abc123/move', {
    method: 'POST',
    body: JSON.stringify({ action: 'HIT' })
  });
  
  if (!response.ok) {
    const error = await response.json();
    
    switch (error.code) {
      case 'GAME_NOT_FOUND':
        // Handle game not found
        break;
      case 'INVALID_MOVE':
        // Handle invalid move
        break;
      case 'VALIDATION_ERROR':
        // Handle validation errors
        break;
      default:
        // Handle other errors
    }
  }
} catch (error) {
  // Handle network errors
}

​
Reactive Error Handling

The Blackjack API is built using Spring WebFlux and returns reactive Mono types. Errors are propagated through the reactive stream and handled by the global exception handler, which returns error responses wrapped in Mono<ResponseEntity<ErrorResponse>>.

Build docs developers (and LLMs) love

Get started for freeTalk to us