Error Handling

In previous versions of Graphene, errors were sent back as protobuf messages. This required the client to read each message and check for an error, and react accordingly.

This has changed in recent versions of Graphene, and this document describes how to use built-in gRPC-level errors.

C# Example

To enable the new style gRPC errors, you can add the metadata to any request like this.

try
{
    var result = client.CreateNetwork(request);
}
catch (RpcException ex) {
    if (ex.StatusCode == StatusCode.InvalidArgument)
    {
        Console.WriteLine("Invalid arguments: " + ex.ToString());
    }
    else
    {
        Console.WriteLine("Something went wrong: " + ex.ToString());
    }
}

See the C# gRPC documentiation for a list of possible status codes.

Python Example

try:
    network = data_api_stub.CreateNetwork(request)
except grpc.RpcError as error:
    if error.code() == grpc.StatusCode.INVALID_ARGUMENT:
        print(f"Invalid arguments: {error.details()}")
    else:
        print(f"Something went wrong: {error.details()}")

Handling gRPC-level errors

In general, errors fall into one of three categories:

1. Non-permanent failures

   • StatusCode.RESOURCE_EXHAUSTED

   • StatusCode.UNAVAILABLE

2. Internal errors

   • StatusCode.INTERNAL

3. User errors

   • All others

Although the following code is written in python, the same pattern should be easily adaptable to your programming language of choice.

#!/usr/bin/python3

import logging
import os
from proto.public import data_management_api_pb2, data_management_api_pb2_grpc
import grpc


def my_grpc_call(grpc_channel):
    stub = data_management_api_pb2_grpc.DataManagementStub(grpc_channel)
    request = data_management_api_pb2.CreateNodeRequest()
    try:
        response = stub.CreateNode(request)
    except grpc.RpcError as e:
        if e.code() in (grpc.StatusCode.RESOURCE_EXHAUSTED, grpc.StatusCode.UNAVAILABLE):
            # You could automatically retry with some backoff algorithm here, if desired.
            print("Graphene is experiencing temporary issues. Please try again later.")
        elif e.code() == grpc.StatusCode.UNKNOWN:
            # Add custom logic here if you would like to prevent your users getting the generic
            # "Contact us at supportanalyzere@verisk.com" message.
            print("Error retrieving results from Graphene! Please contact <developer@mycompany.com>.")
        else:
            # User error. Display the error message to the user so that they can correct their input.
            print(f"Error retrieving results from Graphene: {e.code()}: {e.details()}")

Status Code Meanings

This section gives a list of status codes used in Graphene today. Please note that this list may grow over time, and therefore you should always include a default way to handle errors that don’t match one of these codes.

gRPC Status Codes in use by Graphene

gRPC StatusCode	Meaning
RESOURCE_EXHAUSTED	Quota limits have been reached and Graphene could not service your request at this time. Trying this same request at a later time may be sucessful.
UNAVAILABLE	The service you are calling, or one of its dependencies, is currently unavailable and Graphend could not service your request. Trying this same request at a later time may be sucessful.
INTERNAL	An internal error has occurred on Graphene. The development team is notified every time this occurs. This indicates something wrong on our end.
INVALID_ARGUMENT	The request is invalid. Note that this differs from FAILED_PRECONDITION. INVALID_ARGUMENT indicates arguments that are problematic regardless of the state of the system.
FAILED_PRECONDITION	The request is valid, but something the request depends upon (such as a parquet file) prevents us from servicing the request.
NOT_FOUND	The resource you are requesting was not found.
UNIMPLEMENTED	A feature you are trying to use is not yet implemented.
UNKNOWN	We don’t have enough detail to determine what caused the error.