Error handling

The majority of the Client APIs are request based calls returning completion handlers in response.

All request based APIs return, at a minimum, the following completion handlers:

    onSuccess
    onNoConnection
    onClientError

In addition the majority of requests can also return a onInvalidToken completion handler.

Other completion handlers are defined on a request by request basis. For example registerUser additionally returns the ValidationError & UserAlreadyRegisteredError response handlers.

Each of the error type completion handlers returns a related error object, details of which can be found in the Errors section.

onSuccess

The success block takes two forms:

returning an empty block

    () -> Void

returning an object

    (_ user : [Transaction]) -> Void

onNoConnection

A noConnection error is returned if a network request fails. Reasons for failure can include:

  • No active network available
  • No matching certificate found for the pinned endpoint (see Certificate Pinning).

onClientError

ClientErrors are returned when an error occurs with a biid client method itself. ClientErrors contain two properties to help identity the error:

  • error : The error represented by a ClientException
  • details : An optional string providing additional information where relevant
  • traceID : unique ID generated per API call. Can be used for error tracking (see TraceID)

Documentation

onInvalidToken

If a call fails with an InvalidToken error, it means that the user’s authentication has expired. It is possible to check the error’s Action property to determine what action should be taken to resolve the error:

Swift3

    ...
    onInvalidToken: { (error) in
        if error.action == InvalidTokenError.Action.login {
            // authenticate again to get a new access token
        } else { // InvalidTokenError.Action.retry
           // retry failing call
        }
    }
    ...

ObjC

     ...
     onInvalidToken:^(InvalidTokenError * _Nonnull error) {
         switch (error.action) {
             case InvalidTokenErrorCodeLogin:
                 // Stuff
                 break;

             case InvalidTokenErrorCodeRetry:
                 // Stuff
                 break;

             default:
                 break;
         }
     }
     ...

Documentation

Throwing Calls

A small number of API calls throw errors and should be called with a try or do-catch block in Swift or with an NSError in ObjC e.g.

Swift3

    do {
        try SDK.getClient.initialize()
    }
    catch (let exception) {
        // Handle exception
    }

ObjC

    NSError *error;
    [biidCoreSDK.getClient initialize:&error];
    if (error) {
        // Handle error
    }

TraceID

Each API request generates a unique ID (called a trace_ID) which is then associated with the request. This allows the request to be tracked though the back end micro-services. This id has been exposed via the traceID property in all Error Models models as an aid to debugging any issues with the call i.e. it can be used to find the request in the back end error logs.

The traceID for the request can be accessed as follows:

Swift3

    ...
    onInvalidToken: { (error) in
        let traceID = error.traceID
    }
    ...

ObjC

     ...
     onInvalidToken:^(InvalidTokenError * _Nonnull error) {
        NSString *errorMessageAndTraceID = error.description
     }
     ...

Note: In Objective-C the traceID (if set) is wrapped into the NSError description along with the error message.

e.g. ["urlName": "Not Found."] (traceID: QqTmrct8ph)