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:

{
  "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:

{
  "status": "failed",
  "error": "Submission status must be quoted"
}

Authentication Errors (400 / 401)

Returned when credentials are invalid or a token has expired:

{
  "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.

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:

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

Getting Started

Guides

Webhooks

Error Handling

Error Handling

HTTP Status Codes

Error Response Formats

Validation Errors (422)

Business Rule Errors (400 / 404)

Authentication Errors (400 / 401)

Common Issues and Solutions

”Incorrect username or password”

Token expired (401 on API calls)

“The given data was invalid” (422)

Submission not found (404)

Submission not in required status (404)

Best Practices

​Error Handling

​HTTP Status Codes

​Error Response Formats

​Validation Errors (422)

​Business Rule Errors (400 / 404)

​Authentication Errors (400 / 401)

​Common Issues and Solutions

​”Incorrect username or password”

​Token expired (401 on API calls)

​“The given data was invalid” (422)

​Submission not found (404)

​Submission not in required status (404)

​Best Practices

Error Handling

HTTP Status Codes

Error Response Formats

Validation Errors (422)

Business Rule Errors (400 / 404)

Authentication Errors (400 / 401)

Common Issues and Solutions

”Incorrect username or password”

Token expired (401 on API calls)

“The given data was invalid” (422)

Submission not found (404)

Submission not in required status (404)

Best Practices