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

# Error Handling

> Understanding API error responses and troubleshooting common issues

# Error Handling

The Cover Whale API uses standard HTTP status codes and returns structured error responses to help you diagnose and resolve issues.

## HTTP Status Codes

| Code  | Status               | When It Happens                                                                  |
| ----- | -------------------- | -------------------------------------------------------------------------------- |
| `200` | OK                   | Request succeeded                                                                |
| `201` | Created              | Resource created (vehicles, drivers, endorsements)                               |
| `400` | Bad Request          | Malformed request body, missing required fields, or business rule violation      |
| `401` | Unauthorized         | Missing `AccessToken` header, expired token, or invalid credentials              |
| `404` | Not Found            | Submission not found, or submission not in the required status for the operation |
| `422` | Unprocessable Entity | Validation failed — the request body has the right shape but invalid values      |
| `429` | Too Many Requests    | Rate limit exceeded — wait and retry                                             |

## Error Response Formats

### Validation Errors (422)

Returned when field-level validation fails. The `errors` object maps field names to arrays of error messages:

```json theme={null}
{
  "message": "The given data was invalid.",
  "errors": {
    "insuredInformation.legalName": [
      "The legal name field is required."
    ],
    "garageAddress.garageState": [
      "The garage state field is required."
    ]
  }
}
```

### Business Rule Errors (400 / 404)

Returned when a request is structurally valid but violates a business rule:

```json theme={null}
{
  "status": "failed",
  "error": "Submission status must be quoted"
}
```

### Authentication Errors (400 / 401)

Returned when credentials are invalid or a token has expired:

```json theme={null}
{
  "Error": "Auth Error: Incorrect username or password."
}
```

## Common Issues and Solutions

### "Incorrect username or password"

**Cause**: Invalid credentials or account not yet provisioned.

**Fix**: Verify your username (email) and password. If you haven't received credentials, contact [api-support@coverwhale.com](mailto:api-support@coverwhale.com).

### Token expired (401 on API calls)

**Cause**: The `AccessToken` expires after 3600 seconds (1 hour).

**Fix**: Use the refresh token to obtain a new access token:

```bash theme={null}
curl -X POST https://api.coverwhale.dev/v1/authentication \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-email@example.com",
    "refresh_token": "YOUR_REFRESH_TOKEN"
  }'
```

### "The given data was invalid" (422)

**Cause**: One or more fields failed validation.

**Fix**: Check the `errors` object in the response. Each key is the field path (e.g., `insuredInformation.legalName`) and the values describe what's wrong.

### Submission not found (404)

**Cause**: The `displayId` doesn't exist, or you don't have access to this submission.

**Fix**: Verify the display ID. Submissions are scoped to your agency — you can only access submissions created by your account.

### Submission not in required status (404)

**Cause**: You're trying to perform an operation that requires a specific status. For example, binding requires `Quoted` status.

**Fix**: Check the current submission status with `GET /submission/{displayId}` and ensure it matches the required status for your operation. See the [submission lifecycle](/guides/submissions) for status flow.

## Best Practices

* **Always check the status code first** — branch your error handling on the HTTP status before parsing the body
* **Log the full response** — include headers and body for debugging
* **Handle 401 proactively** — refresh your token before it expires rather than waiting for a failure
* **Implement retry with backoff** for `429` responses — start with 1 second and double on each retry
* **Validate locally first** — check required fields before sending requests to reduce round trips