apps/docs/src/content/docs/en/java-sdk/errors.mdx
Base exception for all Daytona SDK errors.
Subclasses map to specific HTTP status codes and allow callers to catch precise failure conditions without string-parsing error messages:
try {
Sandbox sandbox = daytona.sandbox().get("nonexistent-id");
} catch (DaytonaNotFoundException e) {
// sandbox does not exist
} catch (DaytonaAuthenticationException e) {
// invalid API key
} catch (DaytonaException e) {
// other SDK error
}
public DaytonaException(String message)
Creates a generic Daytona exception.
Parameters:
message String - error descriptionpublic DaytonaException(String message, Throwable cause)
Creates a generic Daytona exception with a cause.
Parameters:
message String - error descriptioncause Throwable - root causepublic DaytonaException(int statusCode, String message)
Creates a Daytona exception with explicit HTTP status code.
Parameters:
statusCode int - HTTP status codemessage String - error descriptionpublic DaytonaException(int statusCode, String message, Map<String, String> headers)
Creates a Daytona exception with HTTP status code and headers.
Parameters:
statusCode int - HTTP status codemessage String - error descriptionheaders Map<String, String> - response headerspublic int getStatusCode()
Returns the HTTP status code, or 0 if not applicable.
Returns:
int -public Map<String, String> getHeaders()
Returns the HTTP response headers, or an empty map if not available.
Returns:
Map\<String, String\> -Raised when API credentials are missing or invalid (HTTP 401).
try {
daytona.sandbox().create();
} catch (DaytonaAuthenticationException e) {
System.err.println("Invalid or missing API key");
}
public DaytonaAuthenticationException(String message)
Creates an authentication exception.
Parameters:
message String - error description from the APIRaised when the request is malformed or contains invalid parameters (HTTP 400).
try {
daytona.sandbox().create(params);
} catch (DaytonaBadRequestException e) {
System.err.println("Invalid request parameters: " + e.getMessage());
}
public DaytonaBadRequestException(String message)
Creates a bad-request exception.
Parameters:
message String - error description from the APIRaised when an operation conflicts with the current state (HTTP 409).
Common causes: creating a resource with a name that already exists, or performing an operation incompatible with the resource's current state.
try {
daytona.snapshot().create(params);
} catch (DaytonaConflictException e) {
System.err.println("A snapshot with this name already exists");
}
public DaytonaConflictException(String message)
Creates a conflict exception.
Parameters:
message String - error description from the APIRaised for network-level connection failures (no HTTP response received).
Raised when the SDK cannot reach the Daytona API due to network issues such as DNS failure, connection refused, or TLS errors.
try {
daytona.sandbox().create();
} catch (DaytonaConnectionException e) {
System.err.println("Cannot reach Daytona API: " + e.getMessage());
}
public DaytonaConnectionException(String message)
Creates a connection exception.
Parameters:
message String - connection failure descriptionpublic DaytonaConnectionException(String message, Throwable cause)
Creates a connection exception with a cause.
Parameters:
message String - connection failure descriptioncause Throwable - root causeRaised when the authenticated user lacks permission to perform an operation (HTTP 403).
try {
daytona.sandbox().delete(sandboxId);
} catch (DaytonaForbiddenException e) {
System.err.println("Not authorized to delete this sandbox");
}
public DaytonaForbiddenException(String message)
Creates a forbidden exception.
Parameters:
message String - error description from the APIRaised when a requested resource does not exist (HTTP 404).
public DaytonaNotFoundException(String message)
Creates a not-found exception.
Parameters:
message String - error description from the APIRaised when API rate limits are exceeded (HTTP 429).
public DaytonaRateLimitException(String message)
Creates a rate-limit exception.
Parameters:
message String - error description from the APIRaised for unexpected server-side failures (HTTP 5xx).
These are typically transient and safe to retry with exponential backoff.
try {
daytona.sandbox().create();
} catch (DaytonaServerException e) {
System.err.println("Server error (status " + e.getStatusCode() + "), retry later");
}
public DaytonaServerException(int statusCode, String message)
Creates a server exception.
Parameters:
statusCode int - HTTP status code (typically 5xx)message String - error description from the APIRaised when an SDK operation times out.
This exception is generated client-side and is not tied to a single HTTP status code.
public DaytonaTimeoutException(String message, Throwable cause)
Creates a timeout exception with a cause.
Parameters:
message String - timeout descriptioncause Throwable - root causepublic DaytonaTimeoutException(String message)
Creates a timeout exception.
Parameters:
message String - timeout descriptionRaised for semantic validation failures (HTTP 422).
Raised when the request is well-formed but the values fail business logic validation (e.g., unsupported resource class, invalid configuration).
try {
daytona.sandbox().create(params);
} catch (DaytonaValidationException e) {
System.err.println("Validation failed: " + e.getMessage());
}
public DaytonaValidationException(String message)
Creates a validation exception.
Parameters:
message String - error description from the API