Skip to main content

​
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

CodeStatusWhen It Happens
200OKRequest succeeded
201CreatedResource created (vehicles, drivers, endorsements)
400Bad RequestMalformed request body, missing required fields, or business rule violation
401UnauthorizedMissing AccessToken header, expired token, or invalid credentials
404Not FoundSubmission not found, or submission not in the required status for the operation
422Unprocessable EntityValidation failed — the request body has the right shape but invalid values
429Too Many RequestsRate 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://app.coverwhale.com/api/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