You're viewing **Apigee Edge** documentation.  
[Go to the
**Apigee X** documentation](http://cloud.google.com/apigee/docs/api-platform/develop/how-handle-java-callout-errors). info

## What is a Java callout?

If you're new to Java callouts, we recommend that you start with [How to create a Java
callout](https://docs.apigee.com/api-platform/samples/cookbook/how-create-java-callout).

## Handling errors in a Java Callout

When you write a Java Callout, you may want to do custom error handling in your Java code. For
example, you may wish to return custom error messages and headers and/or set flow variables with
error information in the proxy flow on Edge.

Let's walk through a simple Java Callout example that illustrates basic custom error handling
patterns. The sample returns a custom error message when an exception occurs. It also places the
error stacktrace into a flow variable, which can be a handy debugging technique.

> [!IMPORTANT]
> **Tip:** See also [How to continue on error in a java callout](https://www.googlecloudcommunity.com/gc/Apigee/How-to-continue-on-error-in-a-java-callout/td-p/45922). Note that unhandled exceptions inside a JavaCallout resource will cause the proxy to enter the Error state, even if `continueOnError` is set to `true`.

### Download the project

To make things simple, you can download this project from the Apigee [api-platform-samples](https://github.com/apigee/api-platform-samples) repository on
GitHub.

1. Download or clone [api-platform-samples](https://github.com/apigee/api-platform-samples) to your system.
2. In a terminal or code editor of your choice, go to the `api-platform-samples/doc-samples/java-error` project.

### The sample Java code

The error handling patterns are straightforward. You can set flow variables in the current
Edge flow context with the `messageContext.setVariable()` method. To return custom
error information, construct an `ExecutionResult` instance and call methods on it to
set the error response and headers.

```java
package com.apigeesample;

import com.apigee.flow.execution.ExecutionContext;
import com.apigee.flow.execution.ExecutionResult;
import com.apigee.flow.execution.spi.Execution;
import com.apigee.flow.message.MessageContext;
import com.apigee.flow.execution.Action;

import org.apache.commons.lang.exception.ExceptionUtils;


public class JavaError implements Execution {
    public ExecutionResult execute(MessageContext messageContext, ExecutionContext executionContext) {

        try {

                String name = messageContext.getMessage().getHeader("username");

                if (name != null && name.length()>0) {
                        messageContext.getMessage().setContent("Hello, " + name + "!");
                        messageContext.getMessage().removeHeader("username");

                } else {
                        throw new RuntimeException("Please specify a name parameter!");
                }

                return ExecutionResult.SUCCESS;

        } catch (RuntimeException ex) {

            ExecutionResult executionResult = new ExecutionResult(false, Action.ABORT);

            //--Returns custom error message and header
            executionResult.setErrorResponse(ex.getMessage());
            executionResult.addErrorResponseHeader("ExceptionClass", ex.getClass().getName());

            //--Set flow variables -- may be useful for debugging.
            messageContext.setVariable("JAVA_ERROR", ex.getMessage());
            messageContext.setVariable("JAVA_STACKTRACE", ExceptionUtils.getStackTrace(ex));
            return executionResult;
        }
    }
}
```

### Compile your code with Maven

The project is set up so that you can compile with Maven. If you want to use
`javac`, we'll include an example as well.

> [!NOTE]
> **Note:** The POM file and configuration for the Maven compile should work, but are offered in the Git repository as an example only. You may need to make adjustments for your environment. If you make changes to the sample code, you may also need to adjust the Maven configuration.

1. Be sure that you have Maven installed:

   ```java
   mvn -version
   ```
2. Execute the script `java-error/buildsetup.sh`. This script installs the required JAR dependencies in your local Maven repo.
3. cd to the `java-error/callout` directory.
4. Execute Maven:

   ```java
   mvn clean package
   ```

   > [!NOTE]
   > **Note:** If you get a Maven error, be sure that you are in the `java-error/callout` directory.

5. If you wish, verify that the JAR file `edge-custom-policy-java-error.jar` was copied to `java-error/apiproxy/resources/java`. This is the required location for JAR files that you wish to deploy with a proxy.

### Compile with javac

If you want to use `javac` to compile the code, you can do something similar to the
following (from the `java-error` directory). The required JAR files are provided for
you in the `java-error/lib` directory.

1. cd to `api-platform-samples/doc-samples/java-error`.
2. Be sure you have javac in your path.  

   ```java
   javac -version
   ```
3. Execute the following javac command:  

   ```java
   javac -d . -classpath ./lib/expressions-1.0.0.jar:./lib/message-flow-1.0.0.jar:. callout/src/main/java/JavaProperties.java
   ```
4. Copy the JAR file to the apiproxy/resources/java directory. This is the required location for JAR files that you wish to deploy with a proxy.  

   ```java
   cp com/apigeesample/JavaProperties.class apiproxy/resources/java
   ```

### Deploy and call the proxy

A deploy script is provided in the `./java-error` directory. But before you run it,
you need to do a quick setup.

1. cd to `api-platform-samples/doc-samples/java-error`
2. If you haven't already done so, open the file `../../setup/setenv.sh` and edit it as indicated with your Apigee account information: your username (the email address associated with your account), your organization name, and the domain you use to make API management calls. For example, for Edge cloud, the domain is `https://api.enterprise.apigee.com`; however, your domain may be different if you're using Edge Private Cloud.
3. Save the `setenv.sh` file.
4. Execute the deploy script:

   ```java
   ./deploy.sh
   ```
5. If the deploy succeeds, execute the invoke script:

   ```java
   ./invoke.sh
   ```

   The invoke script calls a cURL command that looks like this:

   ```java
   curl  http://$org-$env.$api_domain/java-error
   ```

   Because the call does not include a "name" query parameter, the Java code throws a runtime
   error. The proxy returns this message and header:

- Error message: `Please specify a name parameter!`
- Header: `ExceptionClass: java.lang.RuntimeException`

> [!NOTE]
> **Note:** If you look a the Trace Tool in Edge, you'll see that a flow variable is set called JAVA_STACKTRACE. This is a useful technique for debugging, rather than returning a stacktrace to the client.