Errors

Every failure the SDK reports, from a service call, the map or a plugin, names what went wrong with a code from one set. This guide covers what every SDK error shares: its codes, the ones worth retrying and how to read a refused API key.

How each part delivers its errors is in its own guide. A service call rejects with an SDKError. The map reports a TomTomMapError to its error handlers, and so do plugins such as 3D Landmarks.

Error codes

An SDK error’s code is an SDKErrorCode:

• Branch on code, not on message. The codes are the stable part. sdkErrorCodes, exported from the Core bundle, lists them all, under the names the TomTom Navigation SDK gives the same failures.
• Every SDK error also carries sdkVersion, the SDK version to quote in a bug report.

Retrying

An SDK error’s canRetry is true when the failure clears on its own, so the same call is likely to succeed later. That covers RATE_LIMITED, LIVE_SERVICE_NOT_AVAILABLE and NETWORK_NOT_AVAILABLE. On any other code, retrying fails the same way.

Note that a service call answered 429 has already been retried for as long as retry allows before it rejects. The map doesn’t retry its tiles, sprites or glyphs.

A key refused access

A 401 and a 403 are two different problems. INVALID_CREDENTIALS means the API doesn’t know the key. INSUFFICIENT_PERMISSIONS means the key is valid but may not make this request. Its apiErrorCode names the cause of the 403:

A service call’s SDKServiceError and the map’s TomTomMapError both carry apiErrorCode, whether the refused request was a service call, the map style, a tile or a plugin’s data. Both implement APIErrorDetails, from the Core bundle, so one TypeScript function can read either.

Private Preview APIs

A Private Preview API, such as Calculate Reachable Range or the 3D Landmarks tiles, needs access granted to the key. The Freemium and Pay As You Grow plans don’t include it. When such an API answers 'Forbidden', or a proxy answers a 403 with no body, the error says so in two places:

• The message ends with the API that needs access, a link to the Private Preview terms and where to request the access.
• privatePreviewAccess carries the same information as data, a PrivatePreviewAccess of { product, requestAccessURL }, so you can show your own message.

To tell the reader what to do about a refused key, read the same fields on a service call’s error and the map’s:

1
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
2
import { calculateReachableRange, SDKServiceError } from '@tomtom-org/maps-sdk/services';
3

4
const explainRefusedKey = (error) => {
5
    if (error.privatePreviewAccess) {
6
        const { product, requestAccessURL } = error.privatePreviewAccess;
7
        return `${product} needs access on your API key: ${requestAccessURL}`;
8
    }
9
    if (error.apiErrorCode === 'InvalidReferer') return 'Add this domain to the API key';
10
    if (error.code === 'INSUFFICIENT_PERMISSIONS') return 'Enable this API for the API key';
11
    if (error.code === 'INVALID_CREDENTIALS') return 'Check the API key';
12
    return undefined;
13
};
14

15
const map = new TomTomMap({ mapLibre: { container: 'map' } });
16
map.addErrorHandler((error) => {
17
    const explanation = explainRefusedKey(error);
18
    if (explanation) showMessage(explanation);
19
});
20

21
try {
22
    await calculateReachableRange({ origin: [4.9041, 52.3676], budget: { type: 'timeMinutes', value: 30 } });
23
} catch (error) {
24
    if (!(error instanceof SDKServiceError)) throw error;
25
    showMessage(explainRefusedKey(error) ?? error.message);
26
}

Related guides and examples

Related guides

• Request options and errors: what a service call’s error carries, and how to cancel a call or set its deadline.
• Map errors: what the map reports and how it arrives.
• Global configuration: how service calls retry a 429.

Related examples

• Batch geocoding: reads each failure of a batch by its code and canRetry.