Error Handling

Throwing C# Exceptions​

In most cases you won't need to be concerned with ServiceStack's error handling since it provides native support for the normal use-case of throwing C# Exceptions, e.g.:

public object Post(User request) 
{
    if (string.IsNullOrEmpty(request.Name))
        throw new ArgumentNullException("Name");
}

Default Mapping of C# Exceptions to HTTP Errors​

By Default C# Exceptions inheriting from:

  • ArgumentException or SerializationException or FormatException is returned as a 400 BadRequest
  • NotImplementedException or NotSupportedException is returned as a 405 MethodNotAllowed
  • FileNotFoundException is return as 404 NotFound
  • AuthenticationException is returned as 401 Unauthorized
  • UnauthorizedAccessException is returned as 403 Forbidden
  • OptimisticConcurrencyException is returned as 409 Conflict
  • All Other normal C# Exceptions are returned as 500 InternalServerError

Other custom mappings can be added to the Config.MapExceptionToStatusCode dictionary, by implementing IHasStatusCode interface or by returning a HttpError.

WebServiceException​

All Exceptions get injected into the ResponseStatus property of your Response DTO that is serialized into your ServiceClient's preferred Content-Type making error handling transparent regardless of your preferred format - i.e., the same C# Error handling code can be used for all ServiceClients.

try 
{
    var client = new JsonServiceClient(BaseUri);
    var response = client.Send<UserResponse>(new User());
} 
catch (WebServiceException webEx) 
{
    /*
      webEx.StatusCode        = 400
      webEx.StatusDescription = ArgumentNullException
      webEx.ErrorCode         = ArgumentNullException
      webEx.ErrorMessage      = Value cannot be null. Parameter name: Name
      webEx.StackTrace        = (your Server Exception StackTrace - in DebugMode)
      webEx.ResponseDto       = (your populated Response DTO)
      webEx.ResponseStatus    = (your populated Response Status DTO)
      webEx.GetFieldErrors()  = (individual errors for each field if any)
    */
}

Where the StatusCode and StatusDescription are the HTTP StatusCode and Description which shows the top-level HTTP-layer details that all HTTP Clients see. The StatusDescription is typically short and used to indicate the type of Error returned which by default is the Type of the Exception thrown. HTTP Clients normally inspect the StatusCode to determine how to handle the error on the client.

All Service Clients also have access to Application-level Error details which are returned in the Error Response DTO Body where the ErrorCode holds the Exception Type and is what clients would inspect to determine and handle the Type of Exception it is whilst the ErrorMessage holds the Server Exception Message which provides a human-friendly, longer and descriptive description of the Error that can be displayed to the end user. In DebugMode the StackTrace is populated with the Server StackTrace to help front-end developers from identifying the cause and location of the Error.

If the Error refers to a particular field such as a Field Validation Exception, GetFieldErrors() holds the error information for each field that has an Error.

These defaults can be changed to provide further customized error responses by the various options below:

Enabling StackTraces​

By default displaying StackTraces in Response DTOs are only enabled in Debug builds, although this behavior is overridable with:

SetConfig(new HostConfig { DebugMode = true });

Error Response Types​

The Error Response that gets returned when an Exception is thrown varies on whether a conventionally-named {RequestDto}Response DTO exists or not.

If it exists:​

The {RequestDto}Response is returned, regardless of the service method's response type. If the {RequestDto}Response DTO has a ResponseStatus property, it is populated otherwise no ResponseStatus will be returned. (If you have decorated the {ResponseDto}Response class and properties with [DataContract]/[DataMember] attributes, then ResponseStatus also needs to be decorated, to get populated).

Otherwise, if it doesn't:​

A generic ErrorResponse gets returned with a populated ResponseStatus property.

The Service Clients transparently handles the different Error Response types, and for schema-less formats like JSON/JSV/etc there's no actual visible difference between returning a ResponseStatus in a custom or generic ErrorResponse - as they both output the same response on the wire.

Custom Exceptions​

Ultimately all ServiceStack WebServiceExceptions are just Response DTO's with a populated ResponseStatus that are returned with a HTTP Error Status. There are a number of different ways to customize how Exceptions are returned including:

Custom mapping of C# Exceptions to HTTP Error Status​

You can change what HTTP Error Status is returned for different Exception Types by configuring them with:

SetConfig(new HostConfig { 
    MapExceptionToStatusCode = {
        { typeof(CustomInvalidRoleException), 403 },
        { typeof(CustomerNotFoundException), 404 },
    }
});

Returning a HttpError​

If you want even finer grained control of your HTTP errors you can either throw or return an HttpError letting you customize the Http Headers and Status Code and HTTP Response body to get exactly what you want on the wire:

public object Get(User request) 
{
    throw HttpError.NotFound($"User {request.Name} does not exist");
}

The above returns a 404 NotFound StatusCode on the wire and is a short-hand for:

new HttpError(HttpStatusCode.NotFound, 
    $"User {request.Name} does not exist");

HttpError with a Custom Response DTO​

The HttpError can also be used to return a more structured Error Response with:

var responseDto = new ErrorResponse { 
    ResponseStatus = new ResponseStatus {
        ErrorCode = typeof(ArgumentException).Name,
        Message = "Invalid Request",
        Errors = new List<ResponseError> {
            new ResponseError {
                ErrorCode = "NotEmpty",
                FieldName = "Company",
                Message = "'Company' should not be empty."
            }
        }
    }
};

throw new HttpError(HttpStatusCode.BadRequest, "ArgumentException") {
    Response = responseDto,
};

Implementing IResponseStatusConvertible​

You can also override the serialization of Custom Exceptions by implementing the IResponseStatusConvertible interface to return your own populated ResponseStatus instead. This is how ValidationException allows customizing the Response DTO is by having ValidationException implement the IResponseStatusConvertible interface.

E.g. Here's a custom Exception example that returns a populated Field Error:

public class CustomFieldException : Exception, IResponseStatusConvertible
{
  ...
    public string FieldErrorCode { get; set; }
    public string FieldName { get; set; }
    public string FieldMessage { get; set; }

    public ResponseStatus ToResponseStatus() => new ResponseStatus {
        ErrorCode = GetType().Name,
        Message = Message,
        Errors = new List<ResponseError> {
            new ResponseError {
                ErrorCode = FieldErrorCode,
                FieldName = FieldName,
                Message = FieldMessage
            }
        }
    }
}

Implementing IHasStatusCode​

In addition to customizing the HTTP Response Body of C# Exceptions with IResponseStatusConvertible, you can also customize the HTTP Status Code by implementing IHasStatusCode:

public class Custom401Exception : Exception, IHasStatusCode
{
    public int StatusCode => 401;
}

Likewise IHasStatusDescription can be used to customize the StatusDescription and IHasErrorCode for customizing the ErrorCode returned, instead of its Exception Type.

Overriding OnExceptionTypeFilter in your AppHost​

You can also catch and modify the returned ResponseStatus returned by overriding OnExceptionTypeFilter in your AppHost, e.g. ServiceStack uses this to customize the returned ResponseStatus to automatically add a custom field error for ArgumentExceptions with the specified ParamName, e.g:

public virtual void OnExceptionTypeFilter(
    Exception ex, ResponseStatus responseStatus)
{
    var argEx = ex as ArgumentException;
    var isValidationSummaryEx = argEx is ValidationException;
    if (argEx != null && !isValidationSummaryEx && argEx.ParamName != null)
    {
        var paramMsgIndex = argEx.Message.LastIndexOf("Parameter name:");
        var errorMsg = paramMsgIndex > 0
            ? argEx.Message.Substring(0, paramMsgIndex)
            : argEx.Message;

        responseStatus.Errors.Add(new ResponseError
        {
            ErrorCode = ex.GetType().Name,
            FieldName = argEx.ParamName,
            Message = errorMsg,
        });
    }
}

Intercept Service Exceptions​

As an alternative way of customizing Service Exceptions is to override OnExceptionAsync() callback in your Service class (or base class) to intercept and modify Request DTOs, Responses or Error Responses, e.g:

class MyServices : Service
{
    //Return custom error with additional metadata
    public override Task<object> OnExceptionAsync(object requestDto, Exception ex)
    {
        var error = DtoUtils.CreateErrorResponse(requestDto, ex);
        if (error is IHttpError httpError)
        {                
            var errorStatus = httpError.Response.GetResponseStatus();
            errorStatus.Meta = new Dictionary<string,string> {
                ["InnerType"] = ex.InnerException?.GetType().Name
            };
        }
        return Task.FromResult(error);
    }
}

INFO

Return null to continue with default error handling

Custom HTTP Errors​

In Any Request or Response Filter you can short-circuit the Request Pipeline by emitting a Custom HTTP Response and Ending the request, e.g:

this.PreRequestFilters.Add((req,res) => 
{
    if (req.PathInfo.StartsWith("/admin") && 
        !req.GetSession().HasRole("Admin", req.TryResolve<IAuthRepository>())) 
    {
        res.StatusCode = (int)HttpStatusCode.Forbidden;
        res.StatusDescription = "Requires Admin Role";
        res.EndRequest();
    }
});

Or if you need access to the Request DTO you can use a Global Request Filter instead, e.g:

GlobalRequestFilters.Add((req,res,dto) => {
    if (req.Verb == HttpMethods.Post && dto is Authenticate authDto 
        && authDto.provider == CredentialsAuthProvider.Name && !authDto.UseTokenCookie) {
        res.StatusCode = (int)HttpStatusCode.Forbidden;
        res.StatusDescription = "Must use stateless JWT Cookies";
        res.EndRequest();       
    }
});

INFO

To end the Request in a Custom HttpHandler use res.EndHttpHandlerRequest()

Fallback Error Pages​

Use IAppHost.GlobalHtmlErrorHttpHandler for specifying a fallback HttpHandler for all error status codes, e.g.:

public override void Configure(Container container)
{
    this.GlobalHtmlErrorHttpHandler = new RazorHandler("/oops"),
}

For more fine-grained control, use IAppHost.CustomErrorHttpHandlers for specifying custom HttpHandlers to use with specific error status codes, e.g:

public override void Configure(Container container)
{
    this.CustomErrorHttpHandlers[HttpStatusCode.NotFound] = 
        new SharpPageHandler("/notfound");
    this.CustomErrorHttpHandlers[HttpStatusCode.Unauthorized] = 
        new SharpPageHandler("/login");
    this.CustomErrorHttpHandlers[HttpStatusCode.Forbidden] = 
        new SharpPageHandler("/forbidden");
}

Will render the contents of the /notfound.html for 404 NotFound Requests and /login.html page for 401 Unauthorized requests if you're using static HTML, Single Page Apps or #Script Pages.

If you're using Razor instead you can RazorHandler to render /notfound.cshtml or /login.cshtml ServiceStack Razor pages:

public override void Configure(Container container)
{
    this.CustomErrorHttpHandlers[HttpStatusCode.NotFound] = 
        new RazorHandler("/notfound");
    this.CustomErrorHttpHandlers[HttpStatusCode.Unauthorized] = 
        new RazorHandler("/login");
    this.CustomErrorHttpHandlers[HttpStatusCode.Forbidden] = 
        new RazorHandler("/forbidden");
}

Register handlers for handling Service Exceptions​

ServiceStack and its API Design provides a flexible way to intercept exceptions. If you need a single entry point for all service exceptions, you can add a handler to AppHost.ServiceExceptionHandler in Configure. To handle exceptions occurring outside of services you can set the global AppHost.UncaughtExceptionHandlers handler, e.g.:

public override void Configure(Container container)
{
    //Handle Exceptions occurring in Services:

    this.ServiceExceptionHandlers.Add((httpReq, request, exception) => {
        //log your exceptions here
        ...
        return null; //continue with default Error Handling

        //or return your own custom response
        //return DtoUtils.CreateErrorResponse(request, exception);
    });

    //Handle Unhandled Exceptions occurring outside of Services
    //E.g. Exceptions during Request binding or in filters:
    this.UncaughtExceptionHandlers.Add((req, res, operationName, ex) => {
         res.Write($"Error: {ex.GetType().Name}: {ex.Message}");
         res.EndRequest(skipHeaders: true);
    });
}

Async Exception Handlers​

If your handlers need to make any async calls they can use the Async versions instead:

this.ServiceExceptionHandlersAsync.Add(async (httpReq, request, ex) =>
{
    await LogServiceExceptionAsync(httpReq, request, ex);

    if (ex is UnhandledException)
        throw ex;

    if (request is IQueryDb)
        return DtoUtils.CreateErrorResponse(request, new ArgumentException("AutoQuery request failed"));

    return null;
});

this.UncaughtExceptionHandlersAsync.Add(async (req, res, operationName, ex) =>
{
    await res.WriteAsync($"UncaughtException '{ex.GetType().Name}' at '{req.PathInfo}'");
    res.EndRequest(skipHeaders: true);
});

GatewayExceptionHandlers​

Gateway Exception Handlers provide the same Exception Handling callbacks as ServiceExceptions which you can use to intercept Exceptions from Gateway requests:

IAppHost.GatewayExceptionHandlers
IAppHost.GatewayExceptionHandlersAsync

Gateway Exceptions can also be intercepted in your AppHost by overriding:

public override async Task OnGatewayException(IRequest httpReq, object request, Exception ex) => ...

Error handling using a custom ServiceRunner​

If you want to provide different error handlers for different actions and services you can just tell ServiceStack to run your services in your own custom IServiceRunner and implement the HandleException event hook in your AppHost:

public override IServiceRunner<TRequest> CreateServiceRunner<TRequest>(
    ActionContext actionContext)
{           
    return new MyServiceRunner<TRequest>(this, actionContext); 
}

Where MyServiceRunner is just a custom class implementing the custom hooks you're interested in, e.g.:

public class MyServiceRunner<T> : ServiceRunner<T> 
{
    public MyServiceRunner(IAppHost appHost, ActionContext actionContext) 
        : base(appHost, actionContext) {}

    public override object HandleException(IRequest request, 
        T request, Exception ex) {
      // Called whenever an exception is thrown in your Services Action
    }
}

Community Resources​

Edit this page on GitHub