API error handling

The Relativity APIs include error handling options that you can use to build resilient applications, which effectively handle errors. By implementing applications with proper error handling, you can provide a better experience for your users.

All APIs return errors, which may be generally categorized as follows:

Use the guidelines on this page to learn about the types of errors raised by Relativity APIs and how your application code should respond to them.

This page contains the following information:

Errors in RESTful services

RESTful services use the HTTP response status codes to communicate the success or failure of a request. Relativity APIs rely on the following major classes of HTTP response codes:

For more information, see HTTP response status codes on the MDN web site.

Handling errors

Use the class of the status codes to determine the appropriate action for the calling application. The following examples illustrate error handling options for different classes of status codes:

Additionally, HTTP errors usually return a JSON body with details about the issue that occurred. You can log these error payloads and use them for troubleshooting. They may contain field-level detail about the failure of a request, allowing the application to render errors on an HTML form being completed by a user.

Error handling in .NET

In Relativity, the .NET SDKs are wrappers around the RESTful APIs. The Relativity APIs translate all non-success HTTP status codes, such as 400 and 500 codes, into .NET exceptions. They can be handled using standard .NET exception handling techniques. The Relativity SDKs define the following common exception types:

Status code Exception type* Description
500 ServiceException The base class for any exception from a service. Inherit from this class and override the status code.
400 ServiceSerializationException An exception thrown for a serialization or deserialization error.
400 ValidationException An exception that occurs during data validation.
403 NotAuthorizedException An exception that occurs during scope validation.
404 NotFoundException An exception that occurs when a resource isn't found.
404 ServiceNotFoundException An exception raised when the service endpoint can't be found.
409 DataConcurrencyException An exception indicating that the request can't be completed because of a conflict on the server.
409 ConflictException An exception indicating that the request can't be completed because of a conflict on the server.

*The exceptions listed in this table reside in the Relativity.Services.Exceptions namespace.

Some exceptions may contain field-level detail about the failure of a request, such as the ValidationException. In addition to the exceptions listed in the table, individual SDKs may define their own exceptions that provide more details about the failure of a request.

Every exception listed in the table inherits from the ServiceException base type. Due to this implementation, applications can wrap API calls in a try-catch statement with the ServiceException listed as the final block:

    await client.CallOperationAsync(...);
catch (ValidationException valEx)
    // Inform the user that the request needs to be fixed.
catch (ServiceException ex)   // Catches all other API-related errors
    // Log the error.
    // Display a generic failure message to the user or re-throw the error.

Error code changes over time

Enhancements to individual APIs may include returning new HTTP response codes and exception types that provide better information about a failure. Implement your application so that it can accommodate the following changes:

Use the best practices for error handling to ensure that your applications can accommodate these changes. See Best practices for error handling.

Best practices for error handling

Use the following best practices when implementing your error handling strategy:

Community Updates

Aero Developer FAQ Evolving the Platform Most recent release notes
Learn more Learn more Learn more

Additional Resources

Access Third-Party Tools with GitHub     Create .NET Apps Faster with NuGet
Visit github     visit nuget