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

# Errors

> Error response format and common error codes

All AutosnapAI errors use standard HTTP status codes and return a JSON body with a `detail` field describing the error.

## Error response format

```json theme={null}
{
  "detail": "Invalid API key"
}
```

| Field    | Description                                                                               |
| -------- | ----------------------------------------------------------------------------------------- |
| `detail` | Human-readable description of what went wrong. Safe to show to developers, not end users. |

Some errors include additional context in the `detail` string (e.g. which parameter is missing or invalid).

## HTTP status codes

| Status                | Meaning                 | Notes                                                                                   |
| --------------------- | ----------------------- | --------------------------------------------------------------------------------------- |
| `200`                 | Success                 | Response body contains the requested data.                                              |
| `400`                 | Bad request             | Missing or invalid parameter. The `detail` field tells you which.                       |
| `401`                 | Authentication required | API key is missing from the request.                                                    |
| `403`                 | Forbidden               | Invalid or deactivated API key, or authenticated but not allowed (plan/feature gating). |
| `404`                 | Not found               | The resource (vehicle, dealership, webhook) doesn't exist.                              |
| `409`                 | Conflict                | Resource state conflict (e.g. creating a duplicate webhook).                            |
| `422`                 | Unprocessable entity    | Request body validation failed.                                                         |
| `429`                 | Rate limited            | You've exceeded a rate limit. See [Rate Limits](/get-started/rate-limits).              |
| `500`                 | Internal server error   | Our side. Safe to retry with exponential backoff.                                       |
| `502` / `503` / `504` | Service unavailable     | Temporary. Retry.                                                                       |

## Common errors

### Authentication

| Detail                                     | Status | Meaning                                                  |
| ------------------------------------------ | ------ | -------------------------------------------------------- |
| `"API key required"`                       | `401`  | API key is missing from the request                      |
| `"Invalid API key"`                        | `403`  | API key is malformed, deactivated, or not recognized     |
| `"Feature not available on your plan"`     | `403`  | Your plan doesn't include this feature                   |
| `"Dealership not found or not subscribed"` | `404`  | The dealership doesn't exist or isn't under your account |

### Validation

| Detail (example)                           | Status | Meaning                                    |
| ------------------------------------------ | ------ | ------------------------------------------ |
| `"Must provide dealership_url, OR vin..."` | `400`  | A required parameter was omitted           |
| `"Invalid VIN format"`                     | `400`  | VIN is not 17 characters or fails checksum |

### Rate limits

| Detail (example)                            | Status | Meaning                                                              |
| ------------------------------------------- | ------ | -------------------------------------------------------------------- |
| `"Rate limit exceeded: 101/100 per minute"` | `429`  | You're making requests too fast. Detail includes count/limit/window. |
| `{"code": "TEST_QUOTA_EXCEEDED", ...}`      | `429`  | Test key monthly quota exceeded (live keys still work)               |

### Not found

| Detail (example)                           | Status | Meaning                           |
| ------------------------------------------ | ------ | --------------------------------- |
| `"Dealership not found or not subscribed"` | `404`  | No dealership with that ID or URL |
| `"Webhook not found"`                      | `404`  | No webhook with that ID           |
| `"Setup job not found"`                    | `404`  | No setup job with that ID         |

## Retry strategy

Transient errors (`500`, `502`, `503`, `504`, `429`) should be retried with **exponential backoff and jitter**.

```python theme={null}
import time, random, requests

def request_with_retry(url, headers, max_attempts=5):
    for attempt in range(max_attempts):
        r = requests.get(url, headers=headers, timeout=30)
        if r.status_code < 500 and r.status_code != 429:
            return r
        if attempt == max_attempts - 1:
            r.raise_for_status()
        backoff = (2 ** attempt) + random.random()
        time.sleep(backoff)
```

<Warning>
  **Never retry `400`, `403`, or `404` errors.** They're caused by your request, not a transient server issue. Retrying them wastes your quota.
</Warning>

## Debugging

When contacting support about a failed request, include the full error response, the endpoint you called, and the timestamp. Email [support@autosnaplive.com](mailto:support@autosnaplive.com) with these details for the fastest resolution.