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
| Class | HTTP status | Meaning |
|---|---|---|
ValidationError | 400, 422 | The request body or parameters were invalid |
AuthenticationError | 401 | The API key or token is missing, invalid, or expired |
PermissionError | 403 | The credential lacks permission for the action |
NotFoundError | 404 | The resource does not exist or is not visible to the credential |
ConflictError | 409 | The request conflicts with the current state, such as a duplicate name |
RateLimitError | 429 | The rate limit was exceeded |
ServerError | 500 to 599 | The API failed to handle the request |
SpatialFlowError | other 4xx, network failures | Base class, also thrown directly for the cases below |
Properties
Every error has:
| Property | Type | Description |
|---|---|---|
message | string | Short description |
statusCode | number | undefined | HTTP status, when the API responded |
detail | string | undefined | The detail text from the response body |
errorCode | string | undefined | The error_code from the response body, when present |
headers | Record<string, string> | Response headers with string values |
Two subclasses add a field:
ValidationError.errorsis an array of{loc?, msg?, type?}entries, one for each invalid field the API reported.RateLimitError.retryAfteris theRetry-Afterheader in seconds, orundefinedif 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, messageRequest timed out. - A refused connection, unknown host or dropped connection rejects with
ConnectionError, messageUnable 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
WebhookSignatureErrorcomes fromverifyWebhookSignature.JobFailedErrorandJobTimeoutErrorcome frompollJobanduploadGeofences.uploadGeofencesthrows a plainErrorfor a missing file, an unsupported file type, or a failed upload to storage.- API classes you build yourself, such as
new TripsApi(...), reject with anAxiosErrorinstead of the classes above.