Error Handling

Error Handling

Exception Hierarchy

All SDK exceptions extend EssabuApiException:

EssabuApiException (base)
├── ValidationException       (HTTP 422)
├── NotFoundException          (HTTP 404)
├── UnauthorizedException      (HTTP 401)
├── ForbiddenException         (HTTP 403)
├── ConflictException          (HTTP 409)
├── RateLimitException         (HTTP 429)
├── BadRequestException        (HTTP 400)
└── ServerException            (HTTP 5xx)

Catching Exceptions

import com.essabu.common.exception.*;

try {
    essabu.hr().employees().getById(UUID.randomUUID());
} catch (NotFoundException e) {
    // Resource not found (404)
    System.out.println("Not found: " + e.getMessage());
} catch (ValidationException e) {
    // Validation error (422)
    System.out.println("Validation: " + e.getMessage());
    System.out.println("Errors: " + e.getErrors());
} catch (UnauthorizedException e) {
    // Invalid or expired API key (401)
} catch (ForbiddenException e) {
    // Insufficient permissions (403)
} catch (ConflictException e) {
    // Conflict, e.g., duplicate resource (409)
} catch (RateLimitException e) {
    // Rate limit exceeded after retry exhaustion (429)
} catch (ServerException e) {
    // Server error after retry exhaustion (5xx)
} catch (EssabuApiException e) {
    // Any other API error
    System.out.println("Status: " + e.getStatusCode());
    System.out.println("Body: " + e.getResponseBody());
}

Exception Details

Every EssabuApiException provides:

Method	Return Type	Description
getStatusCode()	int	HTTP status code
getMessage()	String	Error message from the API
getResponseBody()	String	Raw response body
getRequestId()	String	Request ID for support

ValidationException additionally provides:

Method	Return Type	Description
getErrors()	Map<String, List<String>>	Field-level validation errors

HTTP Status Code Mapping

Status	Exception	Common Causes
400	BadRequestException	Malformed request, missing required fields
401	UnauthorizedException	Invalid or expired API key/token
403	ForbiddenException	Insufficient permissions for the operation
404	NotFoundException	Resource not found (invalid UUID)
409	ConflictException	Duplicate resource, state conflict
422	ValidationException	Business rule violation, validation failure
429	RateLimitException	Rate limit exceeded (after retries)
5xx	ServerException	Server-side error (after retries)

Retry Behavior

The SDK automatically retries failed requests for transient errors:

Error Type	Retried	Strategy
HTTP 429 (Rate Limit)	Yes	Exponential backoff
HTTP 5xx (Server Error)	Yes	Exponential backoff
HTTP 4xx (Client Error)	No	Thrown immediately
Network/Timeout	Yes	Exponential backoff

Retry Configuration

• Max retries: 3 (configurable)
• Initial delay: 500ms
• Backoff multiplier: 2x (500ms, 1s, 2s)

Essabu essabu = Essabu.builder()
    .apiKey("key")
    .tenantId("tenant")
    .maxRetries(5)                          // Override max retries
    .retryDelay(Duration.ofMillis(1000))    // Override initial delay
    .build();

Best Practices

1. Always catch EssabuApiException as a fallback for unexpected errors.
2. Handle ValidationException specifically to display field-level errors to users.
3. Log the requestId for easier debugging with Essabu support.
4. Do not retry 4xx errors yourself -- they indicate client-side issues that need fixing.