feat: Exceptions now supply ways to get the raw request and response (#614)

* feat: Exceptions from the SDK now have `getRawRequest()` and `getRawResponse()` for better debugging

Author: dragonmantank

CHANGELOG.md

@@ -2,6 +2,9 @@
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+# [9.10.0]
+- Exceptions: Added `getRawRequest()` and `getRawResponse()` methods to `VonageApiResponseException` for debugging API errors
+
 # [9.9.0]
 - Video: Added post-call transcription options
 - Video: Added connections list calls

README.md

@@ -83,7 +83,7 @@ Add the following to your `build.gradle` or `build.gradle.kts` file:
 
 ```groovy
 dependencies {
-    implementation("com.vonage:server-sdk:9.9.0")
+    implementation("com.vonage:server-sdk:9.10.0")
 }
 ```
 
@@ -94,7 +94,7 @@ Add the following to the `<dependencies>` section of your `pom.xml` file:
 <dependency>
     <groupId>com.vonage</groupId>
     <artifactId>server-sdk</artifactId>
-    <version>9.9.0</version>
+    <version>9.10.0</version>
 </dependency>
 ```
 
@@ -121,6 +121,30 @@ the dependency co-ordinates and add `mavenLocal()` to the `repositories` block i
 * For a searchable list of code snippets examples, see [**SNIPPETS.md**](https://github.com/Vonage/vonage-java-code-snippets/blob/main/SNIPPETS.md).
 * For Video API usage instructions, see [the guide on our developer portal](https://developer.vonage.com/en/video/server-sdks/java).
 
+### Error Handling
+
+When an API error occurs, the SDK will throw a `VonageApiResponseException` (or a subclass thereof). This exception
+contains structured information about the error, including the HTTP status code, error title, and detail message.
+
+Starting with version 9.10.0, you can also access the raw HTTP request and response bodies for debugging purposes:
+
+```java
+try {
+    client.getMessagesClient().sendMessage(messageRequest);
+} catch (MessageResponseException ex) {
+    System.err.println("Status: " + ex.getStatusCode());
+    System.err.println("Title: " + ex.getTitle());
+    System.err.println("Detail: " + ex.getDetail());
+    
+    // Access raw request/response for debugging
+    System.err.println("Raw Request: " + ex.getRawRequest());
+    System.err.println("Raw Response: " + ex.getRawResponse());
+}
+```
+
+This is particularly useful when troubleshooting API issues or working with Vonage support, as it allows you to see
+the exact JSON that was sent and received.
+
 ### Custom Requests
 Beginning with v9.1.0, you can now make customisable requests to any Vonage API endpoint using the `CustomClient` class,
 obtained from the `VonageClient#getCustomClient()` method. This will take care of auth and serialisation for you.

pom.xml

@@ -5,7 +5,7 @@
 
   <groupId>com.vonage</groupId>
   <artifactId>server-sdk</artifactId>
-  <version>9.9.0</version>
+  <version>9.10.0</version>
 
   <name>Vonage Java Server SDK</name>
   <description>Java client for Vonage APIs</description>

src/main/java/com/vonage/client/DynamicEndpoint.java

@@ -52,6 +52,7 @@ public class DynamicEndpoint<T, R> extends AbstractMethod<T, R> {
 	protected final Class<? extends VonageApiResponseException> responseExceptionType;
 	protected final Class<R> responseType;
 	protected T cachedRequestBody;
+	protected String cachedRequestBodyString;
 
 	protected DynamicEndpoint(Builder<T, R> builder) {
 		super(builder.wrapper);
@@ -232,7 +233,8 @@ protected final RequestBuilder makeRequest(T requestBody) {
 			applyQueryParams(((QueryParamsRequest) requestBody).makeParams(), rqb);
 		}
 		if (requestBody instanceof Jsonable) {
-			rqb.setEntity(new StringEntity(((Jsonable) requestBody).toJson(), ContentType.APPLICATION_JSON));
+			cachedRequestBodyString = ((Jsonable) requestBody).toJson();
+			rqb.setEntity(new StringEntity(cachedRequestBodyString, ContentType.APPLICATION_JSON));
 		}
 		else if (requestBody instanceof BinaryRequest) {
 			BinaryRequest bin = (BinaryRequest) requestBody;
@@ -266,6 +268,7 @@ protected final R parseResponse(HttpResponse response) throws IOException {
 		}
 		finally {
 			cachedRequestBody = null;
+			cachedRequestBodyString = null;
 		}
 	}
 
@@ -345,6 +348,10 @@ private R parseResponseFailure(HttpResponse response) throws IOException {
 				varex.title = response.getStatusLine().getReasonPhrase();
 			}
 			varex.statusCode = response.getStatusLine().getStatusCode();
+			varex.setRawResponse(exMessage);
+			if (cachedRequestBodyString != null) {
+				varex.setRawRequest(cachedRequestBodyString);
+			}
 			logger.log(Level.WARNING, "Failed to parse response", varex);
 			throw varex;
 		}

src/main/java/com/vonage/client/HttpWrapper.java

@@ -37,7 +37,7 @@
 public class HttpWrapper {
     private static final String
             CLIENT_NAME = "vonage-java-sdk",
-            CLIENT_VERSION = "9.9.0",
+            CLIENT_VERSION = "9.10.0",
             JAVA_VERSION = System.getProperty("java.version"),
             USER_AGENT = String.format("%s/%s java/%s", CLIENT_NAME, CLIENT_VERSION, JAVA_VERSION);
 

src/main/java/com/vonage/client/VonageApiResponseException.java

@@ -34,6 +34,7 @@ public class VonageApiResponseException extends VonageClientException implements
 	protected String title, detail, instance, code, errorCodeLabel, errorCode;
 	protected List<?> errors, invalidParameters;
 	@JsonIgnore protected int statusCode;
+	@JsonIgnore protected String rawResponse, rawRequest;
 
 	protected VonageApiResponseException() {
 	}
@@ -162,6 +163,50 @@ public int getStatusCode() {
 		return statusCode;
 	}
 
+	/**
+	 * Gets the raw HTTP response body that was returned from the API.
+	 * This is useful for debugging when the structured error fields don't provide enough detail.
+	 *
+	 * @return The complete HTTP response body as a string, or {@code null} if not captured.
+	 * @since 9.9.0
+	 */
+	@JsonIgnore
+	public String getRawResponse() {
+		return rawResponse;
+	}
+
+	/**
+	 * Sets the raw HTTP response body. Intended for internal use.
+	 *
+	 * @param rawResponse The complete HTTP response body as a string.
+	 */
+	@JsonIgnore
+	protected void setRawResponse(String rawResponse) {
+		this.rawResponse = rawResponse;
+	}
+
+	/**
+	 * Gets the raw HTTP request body that was sent to the API.
+	 * This is useful for debugging to see exactly what was sent when an error occurred.
+	 *
+	 * @return The complete HTTP request body as a string, or {@code null} if not captured or not applicable.
+	 * @since 9.9.0
+	 */
+	@JsonIgnore
+	public String getRawRequest() {
+		return rawRequest;
+	}
+
+	/**
+	 * Sets the raw HTTP request body. Intended for internal use.
+	 *
+	 * @param rawRequest The complete HTTP request body as a string.
+	 */
+	@JsonIgnore
+	protected void setRawRequest(String rawRequest) {
+		this.rawRequest = rawRequest;
+	}
+
 	@JsonIgnore
 	@Override
 	public String getMessage() {

src/test/java/com/vonage/client/VonageApiResponseExceptionTest.java

@@ -18,7 +18,10 @@
 import com.fasterxml.jackson.annotation.JsonProperty;
 import static org.junit.jupiter.api.Assertions.*;
 import org.junit.jupiter.api.*;
+import java.io.IOException;
+import java.io.InputStream;
 import java.net.URI;
+import java.nio.charset.StandardCharsets;
 import java.util.Collections;
 import java.util.List;
 
@@ -244,4 +247,35 @@ public void testEquals() {
 		ex2.instance = expected.instance;
 		assertEquals(expected, ex2);
 	}
+
+	private String loadJsonResource(String filename) throws IOException {
+		try (InputStream is = getClass().getResourceAsStream(filename)) {
+			if (is == null) {
+				throw new IOException("Could not find resource: " + filename);
+			}
+			byte[] buffer = new byte[1024];
+			StringBuilder sb = new StringBuilder();
+			int bytesRead;
+			while ((bytesRead = is.read(buffer)) != -1) {
+				sb.append(new String(buffer, 0, bytesRead, StandardCharsets.UTF_8));
+			}
+			return sb.toString().trim();
+		}
+	}
+
+	@Test
+	public void testRawRequestAndResponse() throws IOException {
+		String rawRequest = loadJsonResource("raw-request-sms.json");
+		String rawResponse = loadJsonResource("error-422-invalid-channel.json");
+		
+		ConcreteVonageApiResponseException ex = new ConcreteVonageApiResponseException();
+		assertNull(ex.getRawRequest());
+		assertNull(ex.getRawResponse());
+		
+		ex.setRawRequest(rawRequest);
+		ex.setRawResponse(rawResponse);
+		
+		assertEquals(rawRequest, ex.getRawRequest());
+		assertEquals(rawResponse, ex.getRawResponse());
+	}
 }

src/test/java/com/vonage/client/messages/MessagesClientTest.java

@@ -33,6 +33,9 @@
 import com.vonage.client.messages.whatsapp.*;
 import static org.junit.jupiter.api.Assertions.*;
 import org.junit.jupiter.api.*;
+import java.io.IOException;
+import java.io.InputStream;
+import java.nio.charset.StandardCharsets;
 import java.util.*;
 
 public class MessagesClientTest extends AbstractClientTest<MessagesClient> {
@@ -135,6 +138,53 @@ public void testSendMessage401Response() throws Exception {
 		);
 	}
 
+	private String loadJsonResource(String filename) throws IOException {
+		try (InputStream is = getClass().getResourceAsStream(filename)) {
+			if (is == null) {
+				throw new IOException("Could not find resource: " + filename);
+			}
+			byte[] buffer = new byte[1024];
+			StringBuilder sb = new StringBuilder();
+			int bytesRead;
+			while ((bytesRead = is.read(buffer)) != -1) {
+				sb.append(new String(buffer, 0, bytesRead, StandardCharsets.UTF_8));
+			}
+			return sb.toString().trim();
+		}
+	}
+
+	@Test
+	public void testSendMessageExceptionContainsRawRequestAndResponse() throws Exception {
+		String responseJson = loadJsonResource("error-422-invalid-channel.json");
+		stubResponse(422, responseJson);
+		
+		MessageRequest request = SmsTextRequest.builder()
+				.from("447700900001")
+				.to("447700900000")
+				.text("Hello").build();
+		
+		try {
+			client.useRegularEndpoint().sendMessage(request);
+			fail("Expected MessageResponseException to be thrown");
+		}
+		catch (MessageResponseException ex) {
+			// Verify the structured fields are set
+			assertEquals(422, ex.getStatusCode());
+			assertEquals("Invalid channel parameters", ex.getTitle());
+			
+			// Verify the raw response is captured
+			assertNotNull(ex.getRawResponse());
+			assertTrue(ex.getRawResponse().contains("Invalid channel parameters"));
+			assertTrue(ex.getRawResponse().contains("1110"));
+			
+			// Verify the raw request is captured
+			assertNotNull(ex.getRawRequest());
+			assertTrue(ex.getRawRequest().contains("447700900000"));
+			assertTrue(ex.getRawRequest().contains("447700900001"));
+			assertTrue(ex.getRawRequest().contains("Hello"));
+		}
+	}
+
 	@Test
 	public void testSensSmsSandboxFailure() {
 		assertThrows(MessageResponseException.class, () -> client.useSandboxEndpoint()

src/test/resources/com/vonage/client/error-422-invalid-channel.json

@@ -0,0 +1 @@
+{"type":"https://developer.vonage.com/api-errors/messages#1110","title":"Invalid channel parameters","detail":"The value of one or more parameters is invalid.","instance":"bf0ca0bf927b3b52e3cb03217e1a1ddf"}

src/test/resources/com/vonage/client/messages/error-422-invalid-channel.json

@@ -0,0 +1 @@
+{"type":"https://developer.vonage.com/api-errors/messages#1110","title":"Invalid channel parameters","detail":"The value of one or more parameters is invalid.","instance":"bf0ca0bf927b3b52e3cb03217e1a1ddf"}