VEHICLE_ERROR Event

Triggered when Smartcar encounters an error while attempting to retrieve signal data from a vehicle. This event helps you monitor data availability, understand missing or stale signal data and provide an event to trigger a user action to resolve the issue.

When This Event Fires

The VEHICLE_ERROR event fires when:

Smartcar detects an error while retrieving signal data
The vehicle manufacturer’s API returns an error
The vehicle is offline or unreachable
Authentication, permission, or compatibility errors occur

Resolution notifications: When an error condition is resolved (e.g., vehicle comes back online), Smartcar sends another VEHICLE_ERROR event with state set to "RESOLVED". This enables automatic recovery workflows.

Error Categories

Errors are categorized by type and include specific error codes:

Connected Services Account Errors

Issues with the user’s account with the vehicle manufacturer.

Type	Code	Description
`CONNECTED_SERVICES_ACCOUNT`	`ACCOUNT_ISSUE`	General account problem
`CONNECTED_SERVICES_ACCOUNT`	`AUTHENTICATION_FAILED`	Authentication credentials are invalid
`CONNECTED_SERVICES_ACCOUNT`	`PERMISSION`	User lacks necessary permissions
`CONNECTED_SERVICES_ACCOUNT`	`SUBSCRIPTION`	Required subscription is inactive or expired
`CONNECTED_SERVICES_ACCOUNT`	`VIRTUAL_KEY_REQUIRED`	Vehicle requires a virtual key to be configured

Vehicle State Errors

Issues with the vehicle’s connectivity or state.

Type	Code	Description
`VEHICLE_STATE`	`REMOTE_ACCESS_DISABLED`	Remote access is disabled on the vehicle
`VEHICLE_STATE`	`ASLEEP`	Vehicle is in sleep mode
`VEHICLE_STATE`	`UNREACHABLE`	Vehicle is not connected to the internet

Compatibility Errors

Issues with signal availability for the specific vehicle.

Type	Code	Description
`COMPATIBILITY`	`MAKE_NOT_COMPATIBLE`	Vehicle manufacturer doesn’t support this signal
`COMPATIBILITY`	`SMARTCAR_NOT_CAPABLE`	Smartcar cannot retrieve this signal yet
`COMPATIBILITY`	`VEHICLE_NOT_CAPABLE`	This specific vehicle doesn’t support the signal

Permission Errors

Issues with granted permissions.

Type	Code	Description
`PERMISSION`	`null`	Required permission not granted by user

Payload Structure

eventId

string

required

Unique identifier for this event. Use this for idempotency to prevent duplicate processing.

eventType

string

required

Always "VEHICLE_ERROR" for this event type.

vehicleId

string

required

Smartcar vehicle ID for the vehicle this event relates to.

data

object

required

Container for event data.

Show data object

user

object

required

Information about the user who connected the vehicle.

string

Smartcar user ID

vehicle

object

required

Vehicle information

string

Smartcar vehicle ID

make

string

Vehicle manufacturer (e.g., "TESLA", "FORD", "BMW")

model

string

Vehicle model (e.g., "Model 3", "Mustang Mach-E")

year

integer

Vehicle model year

errors

array

required

Array of error objects. Multiple errors may occur simultaneously.

type

string

Error category: CONNECTED_SERVICES_ACCOUNT, VEHICLE_STATE, COMPATIBILITY, or PERMISSION

code

string

Specific error code (see error categories above)

state

string

Error state: "ERROR" when error is active, "RESOLVED" when the issue has been fixed

description

string

Technical description of the error for logging and debugging

suggestedUserMessage

string

User-friendly error message suitable for display to end users. Use this in your application UI.

docURL

string

Link to detailed error documentation. Useful for linking users to troubleshooting guides.

resolution

object

Suggested resolution steps

type

string

Resolution category: RETRY_LATER, CONTACT_SUPPORT, USER_ACTION_REQUIRED, etc.

signals

array

Array of signal objects that were affected by this error.

code

string

Kebab-case signal identifier (e.g., "location-preciselocation")

name

string

Human-readable signal name (e.g., "PreciseLocation")

group

string

Signal category (e.g., "Location", "TractionBattery")

Example Payloads

Error State
Resolved State

Delivered when an error occurs.

{
  "eventId": "5a537912-9ad3-424b-ba33-65a1704567e9",
  "eventType": "VEHICLE_ERROR",
  "vehicleId": "123e4567-e89b-12d3-a456-426614174000",
  "data": {
    "user": {
      "id": "93b3ea96-ca37-43a9-9073-f4334719iok7"
    },
    "vehicle": {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "make": "TESLA",
      "model": "Model 3",
      "year": 2020
    },
    "errors": [
      {
        "type": "COMPATIBILITY",
        "code": "VEHICLE_NOT_CAPABLE",
        "state": "ERROR",
        "description": "The vehicle is incapable of performing your request.",
        "suggestedUserMessage": "Your car is unable to perform this request.",
        "docURL": "https://smartcar.com/docs/errors/api-errors/compatibility-errors#vehicle-not-capable",
        "resolution": {
          "type": "CONTACT_SUPPORT"
        },
        "signals": [
          {
            "code": "location-preciselocation",
            "name": "PreciseLocation",
            "group": "Location"
          },
          {
            "code": "tractionbattery-stateofcharge",
            "name": "StateOfCharge",
            "group": "TractionBattery"
          }
        ]
      }
    ]
  },
  "meta": {
    "version": "4.0",
    "deliveryId": "48b25f8f-9fea-42e1-9085-81043682cbb8",
    "deliveredAt": 1761896351529,
    "webhookId": "123e4567-e89b-12d3-a456-426614174000",
    "webhookName": "Battery Monitoring",
    "mode": "LIVE"
  }
}

Common Error Scenarios

Scenario	Type	Code	Recommended Action
Vehicle offline	`VEHICLE_STATE`	`UNREACHABLE`	Retry later; notify user if persistent
User revoked permissions	`CONNECTED_SERVICES_ACCOUNT`	`PERMISSION`	Prompt user to re-authenticate
Connected services subscription expired	`CONNECTED_SERVICES_ACCOUNT`	`SUBSCRIPTION`	Direct user to renew manufacturer subscription
Signal not supported	`COMPATIBILITY`	`VEHICLE_NOT_CAPABLE`	Remove signal from webhook or handle gracefully
Vehicle asleep	`VEHICLE_STATE`	`ASLEEP`	Retry later; avoid waking vehicle unnecessarily

Processing VEHICLE_ERROR Events

Basic Handler

function handleVehicleError(payload) {
  const { vehicleId, data } = payload;
  const { errors } = data;
  
  errors.forEach(error => {
    if (error.state === 'ERROR') {
      // New error
      logError(vehicleId, error);
      notifyUser(vehicleId, error.suggestedUserMessage);
      
      // Take action based on error type
      if (error.resolution.type === 'RETRY_LATER') {
        scheduleRetry(vehicleId, error.signals);
      } else if (error.resolution.type === 'USER_ACTION_REQUIRED') {
        sendUserNotification(vehicleId, error);
      }
    } else if (error.state === 'RESOLVED') {
      // Error resolved
      logResolution(vehicleId, error);
      clearErrorState(vehicleId, error.code);
      notifyUser(vehicleId, 'Issue resolved, data is now available');
    }
  });
}

Best Practices

Track error state changes

Monitor both ERROR and RESOLVED states to implement automatic recovery workflows.

async function trackErrorState(payload) {
  const { vehicleId, data } = payload;
  
  for (const error of data.errors) {
    if (error.state === 'ERROR') {
      await db.errors.insert({
        vehicleId,
        errorType: error.type,
        errorCode: error.code,
        affectedSignals: error.signals.map(s => s.code),
        detectedAt: new Date()
      });
    } else if (error.state === 'RESOLVED') {
      await db.errors.update(
        { vehicleId, errorCode: error.code },
        { resolvedAt: new Date(), status: 'resolved' }
      );
    }
  }
}

Use suggestedUserMessage for notifications

Display the user-friendly message to vehicle owners instead of technical error descriptions.

function notifyVehicleOwner(error, userId) {
  const message = error.suggestedUserMessage || 
    'We encountered an issue retrieving data from your vehicle.';
  
  sendNotification(userId, {
    title: 'Vehicle Data Unavailable',
    body: message,
    link: error.docURL // Link to troubleshooting docs
  });
}

Implement retry logic for transient errors

Some errors (ASLEEP, UNREACHABLE) are transient. Implement exponential backoff retries.

const TRANSIENT_ERROR_CODES = ['ASLEEP', 'UNREACHABLE'];

function shouldRetry(error) {
  return TRANSIENT_ERROR_CODES.includes(error.code);
}

async function handleTransientError(vehicleId, error) {
  const retryDelays = [60000, 300000, 900000]; // 1m, 5m, 15m
  
  for (const delay of retryDelays) {
    await sleep(delay);
    
    try {
      // Attempt to fetch data again
      const data = await smartcar.fetchSignals(vehicleId, error.signals);
      return data; // Success
    } catch (err) {
      // Still failing, continue retrying
    }
  }
  
  // All retries failed
  notifyUser(vehicleId, 'Unable to reach vehicle after multiple attempts');
}

Handle multiple simultaneous errors

A single VEHICLE_ERROR event can contain multiple errors affecting different signals.

function categorizeErrors(errors) {
  const categorized = {
    transient: [],
    userAction: [],
    permanent: []
  };
  
  errors.forEach(error => {
    if (['ASLEEP', 'UNREACHABLE'].includes(error.code)) {
      categorized.transient.push(error);
    } else if (error.resolution.type === 'USER_ACTION_REQUIRED') {
      categorized.userAction.push(error);
    } else {
      categorized.permanent.push(error);
    }
  });
  
  return categorized;
}

Degrade gracefully in your UI

When errors occur, show stale data with a clear indication that it’s not current.

function displayVehicleData(vehicleId, hasActiveErrors) {
  const data = getLastKnownData(vehicleId);
  
  return {
    ...data,
    isStale: hasActiveErrors,
    staleSince: getLastSuccessfulFetch(vehicleId),
    errorMessage: 'Unable to retrieve current data. Showing last known values.'
  };
}

Error Resolution Tracking

When an error condition is resolved, Smartcar sends a VEHICLE_ERROR event with state: "RESOLVED":

function handleErrorResolution(payload) {
  const { vehicleId, data } = payload;
  
  data.errors.forEach(error => {
    if (error.state === 'RESOLVED') {
      console.log(`Error resolved for ${vehicleId}: ${error.code}`);
      
      // Clear error flags
      clearVehicleError(vehicleId, error.code);
      
      // Resume data collection
      resumeDataCollection(vehicleId, error.signals);
      
      // Notify user
      notifyUser(vehicleId, 'Your vehicle is now connected and data is available');
    }
  });
}

Automatic recovery: Use state: "RESOLVED" events to automatically resume normal operations without manual intervention.

Next Steps

Error Reference

Complete error code documentation

VEHICLE_STATE Event

Learn about successful signal deliveries

Reliability Best Practices

Implement idempotency and retry handling

Delivery Behavior

Understand retry policies

Introduction

Webhooks

Vehicle Authorization & Permissions

Vehicle Data

Vehicle Commands

Management API

Compatibility API

VEHICLE_ERROR Event

When This Event Fires

Error Categories

Payload Structure

Example Payloads

Common Error Scenarios

Processing VEHICLE_ERROR Events

Basic Handler

Best Practices

Error Resolution Tracking

Next Steps

Error Reference

VEHICLE_STATE Event

Reliability Best Practices

Delivery Behavior

Introduction

Webhooks

Vehicle Authorization & Permissions

Vehicle Data

Vehicle Commands

Management API

Compatibility API

​When This Event Fires

​Error Categories

​Payload Structure

​Example Payloads

​Common Error Scenarios

​Processing VEHICLE_ERROR Events

​Basic Handler

​Best Practices

​Error Resolution Tracking

​Next Steps

Error Reference

VEHICLE_STATE Event

Reliability Best Practices

Delivery Behavior

When This Event Fires

Error Categories

Payload Structure

Example Payloads

Common Error Scenarios

Processing VEHICLE_ERROR Events

Basic Handler

Best Practices

Error Resolution Tracking

Next Steps