API client design. What is the best way to return errors from the API?

Question

PHP

Greetings.
There is a question about the design of working with errors in the client of a certain API. How better, more beautiful, easier to work, more true, more fashionable-stylish-youthful, how would you, the developers, like it more?

$result = $apiFacade->getData();
if ($result->isSuccess()) {
    echo 'success: ' . $result->getData() . PHP_EOL;
} else {
    if (ApiClient::ERROR_NOT_ENOUGHT_UNITS === $result->getError()->getCode()) {
        // some actions for this error
    } elseif (ApiClient::ERROR_OBJECT_NOT_EXISTS === $result->getError()->getCode()) {
        // some actions for this error
    } else {
        // some actions for other errors
    }
}

try {
    $result = $apiFacade->getData();
} catch (ApiNotEnoughtUnitsException $exception) {
    // $exception->getCode() вернёт код ошибки
    // $exception->getMessage() вернёт текст ошибки
    // some actions for this error
} catch (ApiObjectNotExistsException $exception) {
    // some actions for this error
} catch (ApiException $exception) {
    // some actions for other errors
}
echo 'success: ' . $result . PHP_EOL;

We are talking about errors received in the API response.
In my opinion, throwing exceptions is good. If somewhere in the application I do not handle an exception, the global exception_handler will catch it and I will know about it from the logs or notifications. On the other hand, there is a possibility that an API error would be the expected result and I would need to get some details about the error. In this case, in the client, I will need to create an instance of an exception, write these very details into its fields, and only then throw it away. Not too hazy?
Who faced, what are the pros and cons of these approaches?

Answer 1

Exceptions and some global handler.
ps ifto switchreplace)

switch($result->getError()->getCode()) {
      case  ApiClient::ERROR_NOT_ENOUGHT_UNITS:
        //...
        break;
      case ApiClient::ERROR_OBJECT_NOT_EXISTS:
        //...
        break;
      default:
        //...
        break;
}

Answer 2

Throwing exceptions is bad, because an insignificant and uninteresting 404 when deleting an object can break the execution stack and give the user a beeeee on the screen. Exceptions are thrown in strongly typed languages ​​because you can't "suddenly" return false instead of the expected type. Go solves this problem by allowing multiple values ​​to be returned.

Answer 3

I faced. Once, too, I puzzled over this question, and did not find a definite answer, because every method has both strengths and weaknesses. Tried different options, including bikes, returning an error code, and even returning associative arrays like {status, result}. Many discouraged throwing exceptions, arguing that the exception should remain an exception and not become business logic (including when the exception's parameters are passed to its constructor when it is thrown, depending on the type of exception). In general, in practice, it turned out that this is quite convenient, it reduces the number of conditions, checks, the code becomes shorter and easier to read, and there are fewer bugs. Almost no effect on speed. In several recent php projects, model error handling was done in a similar way. When implementing rest-api, controllers are simply created for this model. Perhaps someone has a different experience and he will share negative impressions of exceptions, but after choosing this approach, I had no regrets. So, as a developer, this way of error control would be fine.

Answer 4

If the error is unrecoverable by the client and it exits after the occurrence of such an error, then this is an exceptional situation, we work with exceptions, show the user “Try later”, tell the API itself that “I have completed” (if something needs to be reported to this API).
If the client intends to work further (not enough money for the construction? We show the user “There is not enough money”, the API says “ok, not enough, that’s enough”, the client continues to work with the current amount of money), then this is not an exception, but normal work.

Answer 5

Maybe I'm wrong, but in your example it all depends on

$apiFacade->getData()

If an exception can be thrown in this method, then they need to be handled. If the error and code is always returned as a result of the getData method, then the first option should be used. If getData throws an exception, then it will also be in the first example. Only you didn't process it.
That is, the API's error handling in the client depends on how the API returns errors to the client.