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

# Errors

> How the Plugchoice API communicates errors and HTTP status codes.

The Plugchoice API uses standard HTTP status codes and returns JSON error responses.

## Error response format

All error responses include a `message` field:

```json theme={null}
{
  "message": "The given data was invalid."
}
```

Validation errors (422) include field-level details in the `errors` field:

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "name": ["The name field is required."],
    "email": ["The email must be a valid email address."]
  }
}
```

## HTTP status codes

| Code  | Description                                                          |
| ----- | -------------------------------------------------------------------- |
| `200` | OK - Request succeeded                                               |
| `201` | Created - Resource created successfully                              |
| `204` | No Content - Request succeeded with no response body (e.g., deletes) |
| `400` | Bad Request - Malformed request                                      |
| `401` | Unauthorized - Missing or invalid authentication token               |
| `403` | Forbidden - Valid token but insufficient permissions                 |
| `404` | Not Found - Resource does not exist                                  |
| `422` | Unprocessable Entity - Validation errors in request body             |
| `429` | Too Many Requests - Rate limit exceeded                              |
| `500` | Internal Server Error - Unexpected server error                      |
| `504` | Gateway Timeout - The charger could not be reached in time           |

## Common error scenarios

### Authentication errors (401)

Returned when no token is provided or the token is expired/revoked:

```json theme={null}
{
  "message": "Unauthenticated."
}
```

### Authorization errors (403)

Returned when the authenticated user lacks permission for the requested action:

```json theme={null}
{
  "message": "This action is unauthorized."
}
```

### Charger timeout (504)

Some charger actions communicate with the physical charger in real-time. If the charger doesn't respond within the timeout period, a 504 is returned:

```json theme={null}
{
  "message": "Unable to communicate with the charger. Please check the connection and try again."
}
```

This does not necessarily mean the action failed - the charger may still execute the command.