feat: expose structured API error data in RazorpayException

[rzp-slash]

Problem

The Java SDK discards the Razorpay API's structured error JSON and flattens it to a code:description string. Merchants like Coursera have to parse this string to detect error types — fragile when the description itself contains :.

This has been pending since 2020. Multiple Coursera production incidents in 2026 were harder to diagnose because of this limitation.

Changes

RazorpayException.java

• Added JSONObject errorResponse and int statusCode fields
• Added getErrorResponse() — returns the full error JSON object (code, description, source, step, reason, metadata, field)
• Added getStatusCode() — returns the HTTP status code
• Added constructors: (String, JSONObject, int) and (String, int)
• All existing constructors preserved (backward compatible — new fields default to null/0)

ApiClient.java

• throwException() now passes the full error JSON object + status code to RazorpayException
• throwServerException() now passes the status code
• Added JSONException catch in processResponse(), processCollectionResponse(), processDeleteResponse() — handles non-JSON responses (e.g. 503 HTML) gracefully instead of crashing with an unhandled RuntimeException
• Null-safe responseJson handling in throwException()

Usage

try {
    Order order = razorpayClient.Orders.create(request);
} catch (RazorpayException e) {
    // Backward compatible — message is still "BAD_REQUEST_ERROR:The amount must be at least 100"
    System.out.println(e.getMessage());

    // New — structured error data
    JSONObject error = e.getErrorResponse();
    if (error != null) {
        String code = error.getString("code");           // BAD_REQUEST_ERROR
        String field = error.getString("field");          // amount
        String reason = error.getString("reason");        // input_validation_failed
    }

    // New — HTTP status code
    int statusCode = e.getStatusCode();                   // 400
}

Backward Compatibility

• The existing string message format (code:description) is unchanged
• All existing constructors are preserved
• New fields default to null/0 when using old constructors
• No breaking changes to any public API

Testing

• 6 new tests in RazorpayExceptionTest.java covering: structured error response, status code, backward-compatible message, server exception status code, non-JSON response handling, constructor defaults
• All 176 tests pass (170 existing + 6 new)

Context

• Slack thread: https://razorpay.slack.com/archives/C0ANVMNU0SH/p1784708746.720379
• Coursera has been hit by multiple SDK-related pain points — structured error discarding, JSON parse failures on non-JSON responses, and undocumented validation changes
• The stack trace ApiClient.throwException(ApiClient.java:228) appeared explicitly in Coursera's production error reports

[manikrazorpay13]

LGTM.