Check the following sections for help if you experience any issues.

## Lost state in Fleet Engine

When working with Fleet Engine, design your implementation to anticipate
failures. For example, if you issue a request to Fleet Engine to update a
vehicle, it might respond with an error indicating that the vehicle does not
exist. Your implementation should then recreate the vehicle in the new state.

In the extremely unlikely scenario of a catastrophic failure of Fleet Engine,
you may need to recreate most or all vehicles and tasks. If the creation rate
becomes too high, some requests may fail again due to quota issues since quota
checks are in place to avoid denial of service (DOS) attacks. In this case, slow
down the recreation rate using a backoff strategy for reattempts.

### Retries

Be sure your system implements retries for requests to Fleet Engine since they
might fail occasionally. Fleet Engine client libraries issue retries by default.

## Lost state in the driver app

If the driver app crashes, the app must recreate the current state within the
Driver SDK. The app should attempt to recreate tasks to ensure that they exist
and to restore their current states. The app should also recreate and explicitly
set the list of stops for the Driver SDK.

**Note**: These restorations must be done autonomously without relying on
information from Fleet Engine, other than errors indicating if and when an
entity already exists in the database. If an entity does already exist, then
that error can be absorbed and the entity can be updated using its ID.

## Deadline exceeded errors

If you get a `DEADLINE_EXCEEDED` error when calling Fleet Engine, the request
took longer than the configured timeout. Fleet Engine client libraries have
default timeouts, but you might need to adjust them.

For general information on gRPC deadlines, see
[gRPC and Deadlines](https://grpc.io/blog/deadlines/).

To configure the deadline when using the Fleet Engine Java client library, you
can adjust the RPC retry settings. The following example shows how to configure
a custom timeout when setting up the `VehicleService`:

```java
VehicleServiceSettings.Builder settingsBuilder = VehicleServiceSettings.newBuilder();

// Set the timeout to 10 seconds.
settingsBuilder
    .getVehicleSettings()
    .setRetrySettings(
        settingsBuilder.getVehicleSettings().getRetrySettings().toBuilder()
            .setTotalTimeout(java.time.Duration.ofSeconds(10))
            .build());

VehicleServiceClient client = VehicleServiceClient.create(settingsBuilder.build());
```

## Common API errors

This section lists common API errors you might encounter, their causes, and
how to resolve them.

### `NOT_FOUND` (HTTP 404)

The requested entity (like a vehicle, trip, or task) couldn't be found.

- **Cause**: Usually caused by attempting to get, update, or delete an entity using an ID that doesn't exist in the database.
- **Remediation**: Verify that the entity ID is correct and that the entity was successfully created before you attempt to access it.

### `ALREADY_EXISTS` (HTTP 409)

The entity you are trying to create already exists.

- **Cause** : Caused by calling a create method (like `CreateVehicle` or `CreateTrip`) with an ID that is already in use.
- **Remediation**: Either update the existing entity instead, or use a new unique ID for the creation request.

### `PERMISSION_DENIED` (HTTP 403)

You don't have the required permissions to complete the request.

- **Cause**: This typically occurs if your JSON Web Token (JWT) is missing the correct claims, or if the service account signing the JWT is missing the required IAM roles. For example, "JWT does not contain a matching scope for requested trip."
- **Remediation**: Check your Service Account permissions and ensure your JWT claims include the correct scopes for the entity you are trying to access.

### `INVALID_ARGUMENT` (HTTP 400)

One or more of the arguments passed in the request are invalid.

- **Cause** : This can happen for various reasons, such as providing an out-of-range value (e.g., maximum capacity), missing a required field (e.g., a `VehicleType`), or providing invalid coordinates for a pickup point.
- **Remediation**: Review the error message for the specific field that is invalid and ensure your request conforms to the API specification.

### `FAILED_PRECONDITION` (HTTP 400)

The operation was rejected because the system is not in a state required for the
operation's execution.

- **Cause** : Common causes include attempting to change a `COMPLETE` or `CANCELED` trip to a different state, or trying to assign a `CLOSED` task to a vehicle.
- **Remediation**: Ensure the entity's current state allows the operation you are attempting. Check the error message for specific state violations.

### `UNAVAILABLE` (HTTP 503)

The service is unavailable.

- **Cause**: This indicates a transient issue with the Fleet Engine service.
- **Remediation**: The request can safely be retried with exponential backoff.