> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cariqa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stop Charging Error Handling

> Error handling reference for the Connect API stop charging flow.

# Stop Charging Error Handling

Stopping a charging session is the process of ending an existing active charging session for a Connect API user. Before the session can be stopped, the platform validates that the requested session exists, belongs to the requested user, is still active, and can be stopped through the charging provider.

Because this flow depends on both internal charging session state and external charging infrastructure, a stop request can fail for several reasons. This document describes the expected error responses that external customers should handle when calling the **Stop Charging** endpoint.

## Error Response Format

Most stop charging errors are returned using the following structure:

```

json
{
  "detail": "Human-readable error message",
  "error": {
    "type": "error_type",
    "details": "Additional error details"
  }
}
```

Clients should rely on `error.type` for programmatic handling when it is present and `error.details` is for human-readable error details.

Some errors may not include the `error` object and may only return a `detail` field.

Example:

```
json
{
  "detail": "User session with this id was not found"
}
```

***

# Status Codes

## `404 Not Found`

The requested charging session could not be found or is not accessible for the current user/client scope.

This can happen when:

* The provided `session_id` does not exist.
* The session does not belong to the requested user.

Example response:

```
json
{
  "detail": "User session with this id was not found"
}
```

Recommended handling:

* Verify that the `session_id` is correct.
* Refresh the customer’s charging sessions list.

***

## `409 Conflict`

The request is valid, but the charging session cannot be stopped because of the current session state.

### Error type: `already_stopped`

The requested charging session is already inactive or has already been stopped.

This can happen when:

* The customer already stopped the session.
* The session was stopped automatically by the charging provider or station.
* The local session state was updated before the client sent the stop request.
* The client is using stale session data.

Example response:

```
json
{
  "detail": "User session is already stopped",
  "error": {
    "type": "already_stopped",
    "details": "User session is already stopped"
  }
}
```

Recommended handling:

* Treat the session as stopped on the client side.
* Refresh the session details.
* Avoid retrying the stop request unless refreshed session data still shows the session as active.

***

### Error type: `charging_provider_error`

The charging provider did not successfully stop the charging session.

This can happen when:

* The external charging provider rejected the stop request.
* The provider could not process the stop command.
* Communication with the provider failed.

Example response:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "charging_provider_error",
    "details": "Charging provider didn't manage to stop charging"
  }
}
```

Recommended handling:

* Do not assume that charging has stopped.
* Refresh the customer’s active session state.
* If no session exists, allow the customer to retry after a short delay.
* If the issue repeats, suggest using another connector or contacting support.

***

## `500 Internal Server Error`

An unexpected internal error occurred while processing the stop charging request.

### Error type: `unexpected_error`

This can happen when:

* An internal state transition failed.
* An unexpected platform error occurred.
* Required internal data could not be generated.
* An unknown unhandled condition was reached.

Example response:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "unexpected_error",
    "details": "We faced unexpected error. In case it wasn't resolved let us know. Code: 123e4567-e89b-12d3-a456-426614174000"
  }
}
```

Or:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "unexpected_error",
    "details": "Internal error occurred. Please try again a bit later."
  }
}
```

Recommended handling:

* Do not assume that charging has stopped.
* Refresh the active session state before allowing another stopped attempt.
* If an error code is included, store it and provide it to support.
* Show a generic error message to the customer and suggest trying again later.

***

# Recommended Client-Side Handling

When a stop charging request fails:

1. Check the HTTP status code.
2. Check `error.type` when available.
3. Refresh the charging session state after any stop failure.
4. Treat `already_stopped` as a non-critical state conflict.
5. Do not assume the session is still active after a provider error without refetching session details.
6. Avoid aggressive automatic retries.
7. For provider errors, allow the customer to retry after refreshing session state.
8. For unexpected errors, capture the returned support code if present and if the issue persists let us know.

## Summary

| HTTP status | Error type                | Meaning                                    | Recommended action                           |
| ----------- | ------------------------- | ------------------------------------------ | -------------------------------------------- |
| `404`       | Not applicable            | Session was not found or is not accessible | Verify session ID or refresh session data    |
| `424`       | `already_stopped`         | Session is already inactive or stopped     | Treat session as stopped                     |
| `424`       | `charging_provider_error` | Provider failed to stop charging           | Refresh state, show retry option             |
| `500`       | `unexpected_error`        | Unexpected internal error                  | Retry later, contact support with error code |