> ## 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.

# Start Charging Error Handling

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

# Start Charging Error Handling

Starting a charging session is a multi-step process. Before the session can be created, the platform validates the customer state, checks the requested station and connector, verifies billing and payment readiness, performs payment pre-authorization, and sends the start command to the charging provider.

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

## Error Response Format

Most start charging errors are returned using the following structure:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "already_charging",
    "details": "User already has active charging session OR is starting charging"
  }
}
```

Some errors may include additional fields inside `error`, for example a payment intent client secret when additional card authentication is required.

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "pre_authorization_failed",
    "details": "We didn't manage to pre-authorize payment before starting charging. User should try again.",
    "payment_intent_client_secret": "pi_..."
  }
}
```

***

# Status Codes

## `409 Conflict`

The request is valid, but the charging session cannot be started because of the current customer, insufficient billing data, or connector state.

### Error type: `already_charging`

The customer already has an active charging session, or another start charging request is already being processed.

This can happen when:

* The customer already has an active charging session.
* The customer recently sent another start charging request and it is still being processed.

Example response:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "already_charging",
    "details": "User already has active charging session OR is starting charging"
  }
}
```

Recommended handling:

* Do not retry immediately in a loop.
* Refresh the customer’s active charging session state.
* If no active session is visible yet, wait briefly and retry once.
* Show the customer a message that a charging session is already active or starting.

***

### Error type: `billing_data_required`

The customer’s billing data is missing, incomplete, or incorrectly configured.

This can happen when:

* Required billing profile data is missing.
* Billing data exists but is incomplete.
* Billing data cannot be used to issue invoices or process payments.

Example response:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "billing_data_required",
    "details": "Billing data is partially/fully missing. or improperly configured"
  }
}
```

Recommended handling:

* Ask the customer to complete or update their billing information.
* Do not retry start charging until the billing data has been corrected.

***

### Error type: `station_availability_issue`

The selected connector is out of order.

This can happen when:

* The connector is marked as unavailable by the station operator.
* The connector is temporarily out of service.
* The connector cannot accept a new charging session.

Example response:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "station_availability_issue",
    "details": "Connector you were trying to start charging is out of order"
  }
}
```

Recommended handling:

* Ask the customer to choose another connector at the same station.
* If available, refresh station details before showing connector availability.
* Do not retry the same connector immediately unless its status changes.

***

## `404 Not Found`

The requested station or EVSE could not be found.

This can happen when the provided `evse_id` does not exist or no longer available.

Example response:

```
json
{
  "detail": "Station with this evse id was not found"
}
```

Recommended handling:

* Verify that the `evse_id` is correct.
* Refresh station data before allowing the customer to start charging.

***

## `402 Payment Required`

The customer cannot start a new charging session because a payment-related action is required.

### Error type: `payment_error`

The customer has an outstanding unpaid charging session or payment that must be completed before a new session can start.

This can happen when:

* A previous charging session has been unpaid.
* A previous payment failed.
* The customer must complete payment settlement before starting another session.

Example response:

```
json
{
  "detail": "Payment error",
  "error": {
    "type": "payment_error",
    "details": "There is an outstanding payment which user need to finish before starting new charging session"
  }
}
```

Recommended handling:

* Redirect the customer to the outstanding payments flow.
* Require the outstanding payment to be completed before retrying start charging.
* Do not keep retrying the start charging request until the debt is resolved.

***

### Error type: `pre_authorization_failed`

The platform could not pre-authorize the customer’s payment method before starting the charging session.

This can happen when:

* The selected payment method was declined.
* The payment provider returned a general pre-authorization failure.
* The payment method is no longer valid.

Example response without additional authentication data:

```
json
{
  "detail": "Payment error",
  "error": {
    "type": "pre_authorization_failed",
    "details": "We didn't manage to pre-authorize payment before starting charging. User should try again."
  }
}
```

Example response with additional authentication data:

```
json
{
  "detail": "Payment error",
  "error": {
    "type": "pre_authorization_failed",
    "details": "We didn't manage to pre-authorize payment before starting charging. User should try again.",
    "payment_intent_client_secret": "pi_..."
  }
}
```

Recommended handling:

* If `payment_intent_client_secret` is present, use it to complete the required customer authentication.
* If no client secret is present, ask the customer to retry or choose another payment method.
* After successful authentication or payment method update, retry the start charging request.

***

## `424 Failed Dependency`

The platform could not complete the start charging flow because an external dependency was unavailable or rejected the operation.

### Error type: `station_availability_issue`

The platform could not fetch or validate station data.

This can happen when:

* Station data could not be fetched from an external system.
* The station provider is temporarily unavailable.
* The platform cannot reliably confirm station availability.

Example response:

```
json
{
  "detail": "Charging Error",
  "error": {
    "type": "station_availability_issue",
    "details": "We were not able to fetch station details for some reason. Try to change the input or try again a bit later"
  }
}
```

Recommended handling:

* Ask the customer to retry later.
* Refresh station details before retrying.
* If the issue persists, suggest choosing another station or connector.

***

### Error type: `charging_provider_error`

The charging provider did not successfully start the charging session.

This can happen when:

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

Example response:

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

Recommended handling:

* Do not assume that charging has started.
* 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 start 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 started.
* Refresh the active session state before allowing another start 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 start charging request fails:

1. Check the HTTP status code.
2. Check `error.type` when available.
3. Refresh the customer’s active charging session state before retrying.
4. Avoid aggressive automatic retries.
5. For payment-related errors, resolve the payment issue first.
6. For station/provider errors, refresh station data or ask the customer to choose another connector.
7. 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                            |
| ----------- | ---------------------------- | ---------------------------------------------------- | --------------------------------------------- |
| `409`       | `already_charging`           | Customer already has a session or one is starting    | Refresh session state                         |
| `409`       | `billing_data_required`      | Billing data is missing or invalid                   | Ask customer to update billing data           |
| `409`       | `station_availability_issue` | Connector is out of order                            | Choose another connector                      |
| `404`       | Not applicable               | EVSE or station was not found                        | Verify or refresh station data                |
| `402`       | `payment_error`              | Outstanding debt exists                              | Complete outstanding payment                  |
| `402`       | `pre_authorization_failed`   | Payment pre-authorization failed                     | Authenticate, retry, or change payment method |
| `424`       | `station_availability_issue` | Station data cannot be fetched or station is blocked | Retry later or choose another station         |
| `424`       | `charging_provider_error`    | Provider failed to start charging                    | Refresh state, retry later                    |
| `500`       | `unexpected_error`           | Unexpected internal error                            | Retry later, contact support with error code  |