Skip to main content

Errors

Calls made through client.geofences, client.workflows, client.webhooks, client.devices, client.account, and client.storage reject with a SpatialFlowError or one of its subclasses. Import the classes from @spatialflow/sdk and test with instanceof.

Error classes​

ClassHTTP statusMeaning
ValidationError400, 422The request body or parameters were invalid
AuthenticationError401The API key or token is missing, invalid, or expired
PermissionError403The credential lacks permission for the action
NotFoundError404The resource does not exist or is not visible to the credential
ConflictError409The request conflicts with the current state, such as a duplicate name
RateLimitError429The rate limit was exceeded
ServerError500 to 599The API failed to handle the request
SpatialFlowErrorother 4xx, network failuresBase class, also thrown directly for the cases below

Properties​

Every error has:

PropertyTypeDescription
messagestringShort description
statusCodenumber | undefinedHTTP status, when the API responded
detailstring | undefinedThe detail text from the response body
errorCodestring | undefinedThe error_code from the response body, when present
headersRecord<string, string>Response headers with string values

Two subclasses add a field:

  • ValidationError.errors is an array of {loc?, msg?, type?} entries, one for each invalid field the API reported.
  • RateLimitError.retryAfter is the Retry-After header in seconds, or undefined if the header was missing.

error.toString() returns the status, message, and detail on one line.

Handle errors​

import {
SpatialFlow,
SpatialFlowError,
AuthenticationError,
NotFoundError,
RateLimitError,
ValidationError,
} from '@spatialflow/sdk';

const client = new SpatialFlow({apiKey: process.env.SPATIALFLOW_API_KEY});

try {
await client.geofences.appsGeofencesApiGetGeofence('3f1b6a52-0000-0000-0000-000000000000');
} catch (error) {
if (error instanceof NotFoundError) {
console.log('No such geofence');
} else if (error instanceof ValidationError) {
for (const issue of error.errors) {
console.log(issue.loc, issue.msg);
}
} else if (error instanceof RateLimitError) {
console.log(`Retry in ${error.retryAfter ?? 'a few'} seconds`);
} else if (error instanceof AuthenticationError) {
console.log('Check the API key');
} else if (error instanceof SpatialFlowError) {
console.log(error.toString());
} else {
throw error;
}
}

Put the more specific classes first, because every class extends SpatialFlowError.

Network failures​

When the API does not answer, the client rejects with an error that has no statusCode:

  • A timeout rejects with TimeoutError, message Request timed out.
  • A refused connection, unknown host or dropped connection rejects with ConnectionError, message Unable to connect to API.

Both extend SpatialFlowError. These are thrown after the retries below are used up.

Cancelled requests​

A request you cancel with an AbortSignal rejects with axios's CanceledError (axios.isCancel(error) is true), not a SpatialFlowError. Cancelling during a retry wait rejects at once, and nothing further is sent.

Retries​

The client retries GET, HEAD, OPTIONS, PUT and DELETE requests up to maxRetries times (3 by default) after a timeout, a connection failure, or a 429, 500, 502, 503 or 504 response. It waits with exponential backoff, or for the Retry-After header when the response has one. A Retry-After over 30 seconds is not waited out; the request rejects with the RateLimitError or ServerError. Other statuses, such as 501, are not retried. POST and PATCH requests are never retried, so handle RateLimitError and ServerError from those yourself, waiting at least retryAfter seconds when it is set.

Errors from helpers​

  • WebhookSignatureError comes from verifyWebhookSignature.
  • JobFailedError and JobTimeoutError come from pollJob and uploadGeofences.
  • uploadGeofences throws a plain Error for a missing file, an unsupported file type, or a failed upload to storage.
  • API classes you build yourself, such as new TripsApi(...), reject with an AxiosError instead of the classes above.