API Design: Errors passed between APIs

Question

I work as a developer on a few different APIs that make calls to each other. Let's take two and call them API-USER and API-BUSINESS.

A user application makes calls to API-USER, which in turn makes calls to API-BUSINESS

Right now, when API-BUSINESS returns an error the API-USER receives it as a generic error and passes it through to the user.

The concern is that this approach could lead to issues when breaking changes are introduced to the errors in API-BUSINESS.

Are there some API patterns or practices that can lead to a more durable approach to passing errors between APIs?

Is there a better vocabulary to use when talking about this type of error passing?

Answer 1

This can be a tough issue and I'm not sure there's a cut-and-dried answer but my main concern about such an approach would be related to security risks. Errors can expose details that are not appropriate for end users.

I would say, as a default position, you should never relay unknown errors to a user. If you know of specific errors (generally identified by an error code) you should check for those codes and provide your own message for them. Anything that falls outside of these should be reported as an unknown error.

The big downside to that is a poor user experience. "Something happened" doesn't give people a warm fuzzy feeling about a system. However, the risk of exposure is real and often the kind of techno-babble found in errors is not very comforting either. A good approach here is to log the error with a UUID (GUID) and report that id to the user e.g. something like "a system error has occurred. The details of this problem have been logged with the id ... Please record this id and contact support."

Answer 2

I agree with what Jimmy said. When i am faced with such problem then i change the message to more generic in API-USER but log it at both the services.

Let's assume your API-BUSINESS service failed with internal server error then API-USER uses the request context and send the user friendly message, something on the lines failed to load/create/update(depending on request) resource ...... And let the user contact support. Support team can go through logging tools and identify the issue.