.. index:: Error Handling; Errors; Exceptions; Exception Handling
.. _error-handling:


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.


.. index:: Code Examples; Error Handling

C# Example
~~~~~~~~~~

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

.. code:: csharp

   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 <https://grpc.github.io/grpc/csharp/api/Grpc.Core.StatusCode.html>`_ for a list of possible status codes.


Python Example
~~~~~~~~~~~~~~

.. code:: python

   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.

.. code:: python

   #!/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.

.. list-table:: gRPC Status Codes in use by Graphene
   :widths: 25 75
   :header-rows: 1

   * - 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.