Skip navigation
All People > Sascha Preibisch > Sascha Preibisch's Blog > 2017 > April
Sascha Preibisch

API Error Handling

Posted by Sascha Preibisch Employee Apr 20, 2017

Hi everybody!


This week I did a talk about API error handling within CA APIM OAuth Toolkit (OTK). For that I have created a list of general requirements that are important when dealing with APIs. I decided to share that list here since it may be useful for others too.


Here we go:


  1. The API owner must be in control of error messages. This sounds like a given but especially when choosing a middleware product it should be evaluated if internal errors may be returned instead of ones created by the API owner/developer. That is not desired
  2. APIs should return correct error messages. This is another one that should be a given. However, if this is not the case developers will be very confused
  3. Error messages should not reveal sensitive information. The error message should not expose implementation details such as stacktraces. Error messages should be as general and as specific as possible at the same time. For example, returning "authentication failed due to invalid credentials" is general but also specific enough. It would be wrong to return "authentication failed due to the incorrect password 'xyz'"
  4. Error messages should be returned in an expected message format. If the API consumes and produces JSON messages error messages should also be returned in JSON
  5. Error messages should be maintained in a single location. This may be controversial and depends on the API development environment. But if many APIs have to be managed a system that has a central location for maintaining error messages may be used. Otherwise, if the error messages are formulated within those APIs directly, it may be difficult to change or fix them
  6. Same errors should always cause the same error message. If an API implements parameter validation and fails, the produced error message should be the same across all APIs that implement the same validation. This should be consistent for all types of errors
  7. All possible error responses should be documented. Do not let your API consumers guess what errors may occur. Document all possible errors that may be returned. This includes potential reasons for a failed request and also solutions how this can be fixed. For example, if the error says "token is invalid" you may want to document "the given access_token has expired. Repeat the request using a valid access_token"


Financial API (OpenID Foundation - FAPI)

FAPI is still in an early draft but has documented an approach for handling errors. It may be worth taking a look at it:

FAPI error handling - proposal


As usual please leave a comment with any questions or ideas or different views on this topic if you like.

Hello everybody!

I am happy to share with you that OTK and MAG 4.0 have been released. Both come with smaller and bigger changes. The main enhancements were made on this topic:

  • Enable the easy button upgrade


Easy upgrade

OTK and MAG now have specific policies that are marked as customizable where others are either implemented or  suggested to be read only. This enables us to provide a smooth upgrade procedure. Whatever has been implemented in the customizable policies will NOT be replaced with an upgrade.



In the area of customizations we are distinguishing between two different types:

  1. configurations: configure attributes such as token lifetimes in dedicated policies
  2. extensions: extend features OTK provides such as adding your own grant_type in dedicated policies


Both types are implemented as policy fragments that are included in read only policies. The ones made for configurations are generally named like the target policy but with a '#' sign as prefix (e.g.: OTK Token Lifetime Configuration becomes #OTK Token Lifetime Configuration). In this case you would copy a variable from OTK Token Lifetime Configuration and paste it into #OTK Token Lifetime Configuration and set it to your desired value.

The policies for extending OTK's features are generally named with a suffix such as ' ... Extension' (e.g.: OTK User Authentication becomes OTK User Authentication Extension).



Here is a list of my personal highlights of the new release:


  • Upgrades as of 4.x are easy
  • OTK now supports a configurable number of sessions per resource_owner/ client which was limited to 1 in the past
  • OTK now supports JWT signatures with RS256 out of the box
  • OTK now maintains the database (MySQL and Oracle) through a scheduled task. There is no need anymore for an external cron-job
  • Extensions can be used to support custom id_token creation and validation
  • Extensions can be used to support custom grant types
  • OTK uses only two single locations where local cache assertions are used. With that its very easy to replace the local cache assertion with a remote cache assertion and its also easy to audit all data that is being cached and retrieved
  • The Authorization Server's login and consent pages can be modified easily
  • Many configurations/ extensions can be configured per client by leveraging the custom field per client and client_id in OAuth Manager. This should introduce a huge fexibility


MAG received updates but here is my favourite one:

  1. A new feature is the so called enrollment process. This enables an enterprise to publish an app in the app store with a minimal configuration. The full configuration can be retrieved at runtime which makes it very flexible


I surely missed some other enhancements but I wanted to highlight the ones above. If you have further questions or if you need guidance on how to use OTK and MAG as of now please leave a comment. For the complete documentation please go here and search for CA API Management OAuth Toolkit or CA Mobile API GatewayDocumentation