Skip to content
Declare expected errors of your API and generate implementing code automatically.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
example init code commit Sep 13, 2018
generator init code commit Sep 13, 2018
gradle/wrapper init code commit Sep 13, 2018
Api-Error-Handler.iml add missing module Sep 13, 2018
LICENSE Initial commit Sep 13, 2018 Update Jan 8, 2019
build.gradle init code commit Sep 13, 2018
error-handler.iml init code commit Sep 13, 2018 init code commit Sep 13, 2018
gradlew init code commit Sep 13, 2018
publishing.gradle fix maven path Sep 13, 2018
settings.gradle init code commit Sep 13, 2018


Declarative error handling. Define expected behaviour of API and don't worry about actual implementation. It uses your annotations to generate code that will make sure your interface methods get called when specific error code is returned from API.


Specify interface with methods that you want called for different API error codes.

    @AutoHandler // let compiler know it should analyse your class
    public interface SimplerErrorListener { // your code has to implement this interface

        void userError();

        @ErrorCode(codes = {"500", "501", "503"}) // expected error codes
        void multiple();


This will generate implementation calling matching methods when specified error codes are encountered:

    public class SimplerErrorListenerHandler implements ErrorHandler {
      private final ErrorLogger errorLogger;
      private final SimplerErrorListener listener;
      public SimplerErrorListenerHandler(SimplerErrorListener listener, ErrorLogger errorLogger) {
        this.listener = listener;
        this.errorLogger = errorLogger;
      public boolean handle(ErrorPayload error) {
        Map<String, Object> errors = error.errors();
        boolean handled = false;
        switch(error.code()) {
          case "422": {
            return true;
          case "500": {
            return true;
          case "501": {
            return true;
          case "503": {
            return true;
          default:  {
            return false;

Advanced features:

  • payload fields to give meaningful error messages to the user,
        "error": "422",
        "errors": {
          "user": "Email already taken"
  • nested fields:
        "error": "422",
        "errors": {
          "user": {
            "phoneNumber": "Invalid phone number"
  • report error to your bug tracking backend with one annotation,
  • collapse field messages and pass to UI when form config is dynamic,
  • delegated error handler when logic is too complex or awkward to use regular way,

Public API

  • @AutoHandler - class level annotation to let javac annotation processor know that it should analyse contents of your class.
  • @ErrorCode - response field code returned by your backend. Optionally allows you to specify whether error is not expected and should be reported to your crash service.
  • @ErrorField - response field name returned by your backend. Supports nesting and reporting to crash services.
  • @ErrorLogger - if you want to report errors, you need to provide implementation of this interface.
  • @ErrorPayload - as error responses vary, this is the minimal model you need to provide. Your error response should expose String code() (used by @ErrorCode to match errors to methods), String requestId() (required for crash tracking), String message() (developer friendly message) and Map<String, Object> errors that are going to be analysed for error messages for the user.

// TODO: add to your project

Example usages

You can’t perform that action at this time.