Documentation
Table of Contents
1. Developer Portal Guide
1.1. Try out
In order to try out APIs, you need to be logged in to the portal (please register and/or sign in). Once logged in, you need to subscribe to the API product that contains the API you would like to try out. To do so, navigate to the API Products section. Try out is available for all API Products that show a "Subscriptions and API Reference" link. Follow that link for the respective API product you would like to subscribe to. Subscribe to the API product by entering a product subscription name and by pressing the "Subscribe" button. The portal then takes you to your User Profile page where you can view all of your subscriptions.
You have two options to try out an API:
Directly from within Developer Portal
Go back to the respective API Product and select the API resource you would like to try out. Press the Try it button and fill in request parameters into the form.From any desired client application
Note down the subscription key of the subscription to the API product that you would like to try out. Go to the API product, open the respective API resource and copy the displayed URL to call the API from your client application or browser. The subscription key needs to be passed as header parameter "Ocp-Apim-Subscription-Key".
Note: you need to pass at least all required parameters as defined in the definition of the respective API.
Try out responses return static mock data, independent from the request parameters you provide.
2. API Consumer Guide (production APIs)
Below descriptions relate to production APIs and are not applicable to "try it" functionality within this developer portal.
2.1. API keys
An API key must be provided as an HTTP request header (or as a query parameter) when calling an API. If an invalid or no API key is present, the API request is rejected with HTTP 401. API keys identify the consumer and they are used for metrics of API usage; they do not serve as a security measure.
The preferred way of providing the API key is an HTTP request header named APIKey (the header name is case-insensitive). However, if necessary a query parameter can be used instead (e.g., /api/v1/foos?apikey=abc123). If both a header and a query parameter are provided, the query parameter is ignored.
2.2. Status codes and error handling
API Gateway error messages have a fault code that help understand the issue. The list below provides further explanation and remediation suggestions per fault code.
AN3:NF001 (HTTP 404 Not Found)
The specified service was found but the exact path (such as /users or /reports/summary/) and operation (http method, such as GET; POST, etc.) were not found in the OpenAPI definition so details of the message cannot be validated. Therefore message validation fails and an error message is returned.
Remediation: Adapt your request according to the API definition.
AN3:VF001 (HTTP 400 Bad Request)
The request is not valid according to the API definition. Validation of request failed.
Remediation: Adapt your request according to the API definition.
AN3:VF001 (HTTP 500 Internal Server Error)
The response body returned by the target endpoint is not valid according to the API definition. Validation of response body failed.
Remediation: Contact the API provider with the error details. (Either API implementation has to be adapted/fixed, or API definition has to be changed.)
AN3:VF002 (HTTP 400 Bad Request)
There can be several reasons, for example, the request body may be invalid, or a request body is sent to an API endpoint that doesn't specify a request body.
Remediation: Adapt your request according to the API definition. Make sure the specified content types are used.
AN3:VF002 (HTTP 500 Internal Server Error)
There can be several reasons, for example, the response body may be invalid.
Remediation: Contact the API provider with the error details.
AN3:VF003 (HTTP 400 Bad Request)
An encrypted non-sensitive identifier was expected but not found, and therefore the request failed. It is not valid according to the API definition.
Remediation: Ensure that the value is encrypted.
AN3:ISE001 (HTTP 500 Internal Server Error)
Unexpected validation error.
Remediation: Contact the API provider with the error details.
AN3:400-99 (HTTP 400 Bad Request, Invalid Entity)
In multi-entity environments the caller may need to add an X-UBS-Entity header with a valid UBS legal entity.
Remediation: Add a valid X-UBS-Entity header to your request.
AN3:401-99 (HTTP 401 Unathorized)
When requesting the API, no API key was provided, or the provided API key was not valid.
Remediation: Provide a valid API key (more information under "API keys" on this page).
AN3:404-99 (HTTP 404 Not Found)
The API Proxy Bundle is not fully deployed.
Remediation: Contact the API provider with the error details.
AN3:429-99 (HTTP 429 Too Many Requests)
The consumer application is over quota.
Remediation: Stop calling the endpoint. If a Retry-After header is provided, wait for the specified number of seconds before calling again.
AN3:500-99 (HTTP 500 Internal Server Error)
Target endpoint has returned an error.
Remediation: Contact the API provider with the error details.
AN3:RDF001 (HTTP 500 Internal Server Error)
Internal error while processing UBS Risk Score.
Remediation: Contact the API provider with the error details.
AN3:10003 (HTTP 401 Unauthorized)
Token Not Found: ASN1 token verification failed due to missing token.
Remediation: Verify if the ASN1 token is correctly sent with the request (check csiv2 header).