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.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 a plain SpatialFlowError, with no statusCode:

• A timeout gives the message Request timed out.
• A refused connection or unknown host gives Unable to connect to API.

TimeoutError and ConnectionError are exported, but the client does not throw them, so check statusCode rather than the class to tell a network failure from an API error.

Retries

The client does not retry requests. The maxRetries option is accepted but unused. Retry RateLimitError and ServerError 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.