Troubleshooting API Invocation

Owned by Louis Zelus
Last updated: Sep 12, 2022

Invoking an API through the API Manager can be frustrating when it doesn't work.  Here we provide some tips and tricks for identifying the problem.

How to determine if an error is caused by the API Manager or the back-end service

It is very common to run into issues, either while developing an API to use the API Manager, or while porting an API to the API Manager. Sometimes, it can be confusing to discern whether an error is coming from the back-end service, or from the API Manager itself. Luckily, API Manager errors are easily-discernible from back-end errors, as explained below.

All API Manager-generated errors will be returned in XML format, and will be namespaced to https://wso2.org. For example:

<am:fault xmlns:am="http://wso2.org/apimanager">
  <am:code>101500</am:code>
  <am:type>Status report</am:type>
  <am:message>Runtime Error</am:message>
  <am:description>Error in Sender</am:description>
</am:fault>

This error was produced by the API Manager. We can tell because A) it is in XML format, and B) it contains the namespace "http://wso2.org/apimanager." This indicates that the error was returned by the API Manager. If an error does not follow the format prescribed above, it must have been returned from the back-end service. For example:

{"status" : "error", "error" : "Missing Credentials"}

This error has been returned from the back-end service. We can tell because it is not in XML and more specifically, because it is not name spaced to "http://wso2.org."

For any errors produced by the API Manager, you can browse the documentation found in this space to look for common solutions. We are more than happy to help you solve any problems you face. For help with any errors produced by the back-end service, get in touch with the team in charge of that specific back-end service. Technical and Business-Owner information can typically be found on the service's page in the API store

APIM Error Messages

See the standard APIM error code list at

https://docs.wso2.com/display/AM210/Error+Handling


Below are some of the error messages returned by the API Manager under different scenarios.

Several scenarios result in similar or identical error messages. So if you receive a error message similar to an example below that does not necessarily mean that you're experiencing the described problem. That being said, we've attempted to document to most common problems and the errors they produce.

If the incoming request has a Accept HTTP header specifying JSON then the XML messages below will be translated to JSON before returning.


Invalid API Context / Version (can't identify/find the requested API)

One of the first steps the API Manager does is determine which API you're calling.  It does this by mapping the first section of the URI Path to the context and version of an API.  When invoking an API with the wrong context / version (https://api.ucsd.edu:8243/echo/v1 instead of https://api.ucsd.edu:8243/echo/1.0.0) or a API that doesn't exist  (https://api.ucsd.edu:8243/this_api_doesn't_exist/v1/getStuff) you get the following error:

<am:fault xmlns:am="http://wso2.org/apimanager">
    <am:code>404</am:code>
    <am:type>Status report</am:type>
    <am:message>Not Found</am:message>
    <am:description>The requested resource (/vacx/v1/contacts?student_id=A02774880) is not available.</am:description>
</am:fault>

Invalid Resource

After determining the API, the API Manager next checks the resource your attempting to access ( "emergencyinfo" in the following example: https://api.ucsd.edu:8243/student/1.0/emergencyinfo/phone).  If the specified API doesn't have that resource you get:

<am:fault xmlns:am="http://wso2.org/apimanager">
    <am:code>404</am:code>
    <am:type>Status report</am:type>
    <am:message>Runtime Error</am:message>
    <am:description>No matching resource found for given API Request</am:description>
</am:fault>

Invalid Request Method

Each resource has a list of allowed HTTP Methods, if you use one that isn't allowed:

<am:fault xmlns:am="http://wso2.org/apimanager">
    <am:code>405</am:code>
    <am:type>Status report</am:type>
    <am:message>Runtime Error</am:message>
    <am:description>Method not allowed for given API resource</am:description>
</am:fault>

For example, if a resource is setup to accept HTTP POST requests, sending a GET request will generate this error

No Access Token

If you invoke an API that requires authentication (most do) you must provide a OAuth token in a HTTP Hearer.  The header must be called "Authorization" and begin with the text "Bearer " followed by your token.  Failure to provide the header or sending one that doesn't start with "Bearer " results in:

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
    <ams:code>900902</ams:code>
    <ams:message>Missing Credentials</ams:message>
    <ams:description>Required OAuth credentials not provided. Make sure your API invocation call has a header: "Authorization: Bearer ACCESS_TOKEN"</ams:description>
</ams:fault>

Invalid Access Token

If the OAuth token is invalid (malformed, expired, fake) the following error is reutrned:

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
    <ams:code>900901</ams:code>
    <ams:message>Invalid Credentials</ams:message>
    <ams:description>Access failure for API: /vac/v1, version: v1 status: (900901) - Invalid Credentials. Make sure you have given the correct access token</ams:description>
</ams:fault>

Incorrect Access Token Type

There are multiple way's to get an OAuth token, broadly they fall into two groups.  Those that require the user to authenticate and those that don't.  If an API requires user data and the provided token was generated using a method that doesn't authenticate the user, the following error is returned:

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
    <ams:code>900905</ams:code>
    <ams:message>Incorrect Access Token Type is provided</ams:message>
    <ams:description>Access failure for API: /vac/v1, version: v1 status: (900905) - Incorrect Access Token Type is provided</ams:description>
</ams:fault>

Using the Client Credentials grant type does not identify the user making the call, only the application.  The "generate token" button in the API Store generates this style of token.  

Unfortunately this setting isn't shown in the API Store.  When documenting their API, developers should specify that Authorization Grant or Implicit need to be used when retrieving an Access Token.

Wrong Scope

Scope is a feature that allows more fine grained control of API access.  It allows the API consumer to list the operations they want to do and the APIM to return a subset of operations they are allowed to do. In practice it's tied to roles which aren't utilized in UCSD's current APIM setup.  If you invoke an API operation that requires a scope that wasn't included on the provided access token (either because that scope wasn't requested, or because it wasn't granted) you get the following error:

<ams:fault xmlns:ams="https://wso2.org/apimanager/security">
    <ams:code>900910</ams:code> 
    <ams:message>The access token does not allow you to access the requested resource</ams:message>
   <ams:description>Access failure for API: /sampleShopping, version: 1.0.0 with key: d1d8577a030019c5f9e2187742a3e7
   </ams:description>
</ams:fault>


Not Subscribed

If the Application associated with the ClientID used to generate the OAuth token does not have an active subscription to the API, the following error is returned:

<ams:fault xmlns:ams="http://wso2.org/apimanager/security">
    <ams:code>900908</ams:code>
    <ams:message>Resource forbidden </ams:message>
    <ams:description>Access failure for API: /vac/v1, version: v1 status: (900908) - Resource forbidden </ams:description>
</ams:fault>

HTTPS Not Enabled

If for some reason the API is deployed without the https protocol enabled you will recieve the following message when attempting to invoke it:

<am:fault xmlns:am="http://wso2.org/apimanager">
    <am:code>403</am:code>
    <am:type>Status report</am:type>
    <am:message>Forbidden</am:message>
    <am:description>Unsupported Transport [ https ]. The requested resource (/auditing/v1/audits) is not available.</am:description>
</am:fault>

The API Manager only accepts HTTPS connections, not selecting this option makes the API un-usable.

Send Timeout

When the backend is not responding in time the APIM will generate and return the following error message

<am:fault xmlns:am="http://wso2.org/apimanager">
   <am:code>101504</am:code><am:type>Status report</am:type>
   <am:message>Runtime Error</am:message>
   <am:description>Send timeout</am:description>
</am:fault>


Matching the ClientId to Application

Code and tests will have a ClientId hard coded (or set in properties/preferences), but the API Store interface deals with Applications.  Unfortunatly there's no way to lookup the Application from the ClientID, short of manually checking each Application's  ClientId for a match.  
  1. Log into the API Store https://api.ucsd.edu/ or https://api-qa.ucsd.edu/store/
  2. Click Applications in the upper right
  3. Click on an Application in the list
  4. Click on the "Production Keys", "QA Keys" or "Dev Keys" tab
  5. Click "Show Keys"
  6. Check if the ClientID matches the one used by the code.

Checking the status of a Subscription

  1. Log into the API Store https://api.ucsd.edu/ or https://api-qa.ucsd.edu/store/
  2. Click Applications in the upper right
  3. Click on an Application in the list
  4. Click on the "Subscriptions" tab
  5. If the API is not listed, then there is no subscription from the Application to that API.
  6. If the "Status" column shows "ON_HOLD" the subscription is awaiting approval from the Business Owner.
  7. If the "Status" column shows "UNBLOCKED" the subscription is active and ready to use.

If your Application doesn't have a subscription:

  1. Log into the API Store https://api.ucsd.edu/ or https://api-qa.ucsd.edu/store/
  2. Find the API using the search feature or by paging through the availiable APIs
  3. Select the Application you want to subscribe from the combo box in the upper right (only your applications that don't have a subscription will be listed)
  4. Select Subscribe
  5. You should recieve an email that your subscription is being reviewed.  Once approved you will recieve another email letting you know you can begin using the API.

If you Applications subscription is "ON_HOLD" and you want to cancel the request, either because you made a mistake or want to try again:

  1. Log into the API Store https://api.ucsd.edu/ or https://api-qa.ucsd.edu/store/
  2. Click Applications in the upper right
  3. Click on an Application in the list
  4. Click on the "Subscriptions" tab
  5. Find the API and click on the "unsubscribe" link.