SDK Error Handling

Handling Errors

The FeedFM SDK provides multiple mechanisms for error reporting. It is essential to implement proper error handling to ensure your application behaves reliably and predictably.

Return Values

Some methods in the SDK return a BOOL value to indicate immediate success or failure. These methods may initiate a long-running asynchronous operation, and the returned value only signifies whether that operation was successfully started.

Always handle the return value appropriately, and refer to the SDK documentation to understand what errors may occur and under which conditions.

Example:

Swift

let result = FMAudioPlayer.shared().play()
if !result {
    // Could not initiate play operation
}

Objective-C

const BOOL result = [[FMAudioPlayer sharedPlayer] play];
if (result == NO) {
    // Could not initiate play operation
}

Completion Handlers

Methods that accept completion handlers use blocks to deliver the result of an operation. Completion handlers allow you to clearly associate outcomes with the method calls that triggered them.

If a method is available in both synchronous and asynchronous variants (i.e., with and without a completion handler), it is strongly recommended to use the version with a completion handler to avoid missing potential errors reported by the SDK.

Example:

Swift

FMAudioPlayer.shared().like { error in
    if let error {
        print("Error occurred while liking: \(error.localizedDescription)")
    }
}

Objective-C

[[FMAudioPlayer sharedPlayer] likeWithCompletion:^(NSError * _Nullable error) {
    if (error) {
        FMLogError(@"Error occured while liking: %@", error.localizedDescription);
    }
}];

FMAudioPlayerDelegate

Some errors are not directly associated with specific user-initiated method calls. These can occur during the SDK’s background operations—for example, network failures or server-side issues while streaming audio.

To be notified of such events, implement the FMAudioPlayerDelegate protocol.

Example:

Note that FMAudioPlayerDelegate has two required methods: audioPlayerDidReceiveError: and didFailToLoadAudioItems:error:.

Swift

FMAudioPlayer.shared().delegate = self

...

func audioPlayerDidReceiveError(_ error: Error) {
    print("FMAudioPlayer received error: \(error)")
}

func didFail(toLoad items: [FMAudioItem], error: any Error) {
    print("FMAudioPlayer failed to load items: \(error)")
}

Objective-C

[FMAudioPlayer sharedPlayer].delegate = self;

...

- (void)audioPlayerDidReceiveError:(nonnull NSError*)error {
    NSLog(@"FMAudioPlayer received error: %@", error);
}

- (void)didFailToLoadAudioItems:(nonnull NSArray<FMAudioItem*>*)items error:(nonnull NSError*)error {
    NSLog(@"FMAudioPlayer failed to load items: %@", error);
}

NSNotifications

The SDK posts NSNotification objects to report player state changes — playback state, the current item, elapsed time, skip availability, like status, and the active station — and these remain the supported way to observe state. See the notifications declared in the FMAudioPlayer.h header file for the full list.

For error reporting, however, prefer the mechanisms described above (return values, completion handlers, and FMAudioPlayerDelegate) over notifications: they associate each error directly with the operation that caused it.

Errors

The SDK reports errors using instances of the FeedFMError class. For a comprehensive list of possible error codes and descriptions, refer to the FeedFMError.h header file.

In some cases, the FeedFMError object may include an underlying error, which can provide additional context and insight into the cause of the failure.

Swift

let nsError = error as NSError
if let underlyingError = nsError.userInfo[NSUnderlyingErrorKey] as? NSError {
    print("Underlying error: \(underlyingError)")
}

Objective-C

NSError *underlyingError = error.userInfo[NSUnderlyingErrorKey];
if (underlyingError) {
    NSLog(@"Underlying error: %@", underlyingError);
}

List of Error Codes

Error Code	Description
FeedFMErrorCodeNetworkFailure	Network connection failed. Please check your internet connection and try again.
FeedFMErrorCodeInvalidRequest	The request was malformed or contained invalid parameters.
FeedFMErrorCodeInvalidResponse	Received an invalid response from the server.
FeedFMErrorCodeUnauthorized	Unauthorized access. Check your credentials or authentication token.
FeedFMErrorCodeInvalidRegion	Invalid region, service is not available in your current geographic region.
FeedFMErrorCodeUnexpectedError	An unexpected error occurred.
FeedFMErrorCodeRequestTimeout	The request timed out. Please try again.
FeedFMErrorCodeClientCreationFailed	Failed to create the client.
FeedFMErrorCodeSessionNotAvailable	Session is not available. Ensure that a session is created before making this request.
FeedFMErrorCodeSessionRequestError	An error occurred while sending a request to the session.
FeedFMErrorCodeSessionCreationFailed	Failed to create a session.
FeedFMErrorCodeSessionUpdateFailed	Failed to update the session.
FeedFMErrorCodeSkipNotAllowedForSimulcast	Skipping is not allowed for simulcast stations.
FeedFMErrorCodeSkipAlreadyInProgress	Skip operation is already in progress.
FeedFMErrorCodeLikeNoActiveStation	No active station to like.
FeedFMErrorCodeLikeNoActiveItem	No active item to like.
FeedFMErrorCodeLikeNotAllowed	Like operation is not allowed.
FeedFMErrorCodeDislikeNoActiveStation	No active station to dislike.
FeedFMErrorCodeDislikeNoActiveItem	No active item to dislike.
FeedFMErrorCodeDislikeNotAllowed	Dislike operation is not allowed.
FeedFMErrorCodeUnlikeNoActiveStation	No active station to unlike.
FeedFMErrorCodeUnlikeNoActiveItem	No active item to unlike.
FeedFMErrorCodeUnlikeNotAllowed	Unlike operation is not allowed.
FeedFMErrorCodePlayerNotInitialized	Audio player is not initialized.
FeedFMErrorCodePlayerPlaybackUnavailable	Playback is unavailable.
FeedFMErrorCodePlayerNoItemsToLoad	No audio items are available to load.
FeedFMErrorCodePlayerCouldNotLoadItem	Could not load the requested item.
FeedFMErrorCodePlayerNoMoreMusic	Unable to retrieve more music for the current station/birate/codec configuration.
FeedFMErrorCodePlayerCouldNotSetStation	Could not set the requested station.
FeedFMErrorCodePlayerPrepareTimeout	Preparing the player timed out.
FeedFMErrorCodeUnknown	An unknown error occurred. Please try again or contact support if the issue continues.