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
`409`	Conflict	A cancellation guard or an existing saved approval’s notice readiness blocks execution
`422`	Unprocessable Entity	Field validation failed or the operation requires business review, such as a cancellation notice-date hold
`429`	Too Many Requests	Rate limit exceeded — wait and retry
`500`	Server Error	A server failure; an intent-backed cancellation approval can already be saved and require notice-continuation review

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

Cancellation Notice Holds (422)

Cancellation request or approval can return 422 when enabled notice rules cannot safely finalize the dates. Distinguish this from field validation using reason_code: cancellation_notice_manual_review:

{
  "error": "The minimum cancellation notice date exceeds the policy expiration; manual review is required.",
  "reason_code": "cancellation_notice_manual_review",
  "cancellation_notice": {
    "phase": "approval",
    "held": true,
    "hold_reason": "The minimum cancellation notice date exceeds the policy expiration; manual review is required.",
    "minimum_date": "2026-10-16",
    "enabled": true
  }
}

The decision may contain further rule, date-change, and measurement fields. Resolve the hold with Cover Whale before retrying; the API does not shorten the notice minimum to fit expiration. A held proposal in advisory metadata on a successful response is different from this 422 refusal. See cancellation dates and rollout.

Saved Cancellation Approval Needs Notice Review (500 / 409)

A notice-continuation failure differs from a precommit notice-date hold. cancel-approve returns 500 when an intent-backed approval is already saved but its notice handoff needs review or safe recovery. cancel returns 409 when that saved approval’s notice readiness blocks finalization. Inspect approval_saved and the continuation receipt:

{
  "error": "Cancellation approval is saved; notice continuation requires review or safe recovery.",
  "reason_code": "cancellation_notice_continuation_review",
  "approval_saved": true,
  "submission_number": "123456789",
  "transaction_id": 1,
  "transportation_submission_id": 12345,
  "submission_status": "Pending Cancellation",
  "notice_continuation": {
    "id": 42,
    "phase": "held",
    "reason_code": "external_attempt_unconfirmed"
  },
  "effective_date_transaction": "2026-11-09",
  "effective_date_transaction_al": "2026-12-09",
  "effective_date_transaction_wc": null,
  "cancellation_notice": {
    "phase": "approval",
    "notice_minimum_required": true,
    "enabled": true,
    "held": false,
    "wc_action": "not_applicable"
  }
}

There is no status: success in this refusal. Keep the receipt and reconcile with Cover Whale; do not blindly repeat cancel-approve or an uncertain filing or queue publication. A generic error-only 500 does not establish that approval was saved. Required physical-print chain handoff must also be confirmed before finalization; PDF readiness alone is insufficient. Queue handoff, filing acceptance, and provider delivery remain separate facts; readiness does not promise exactly-once delivery.

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)

Cancellation Notice Holds (422)

Saved Cancellation Approval Needs Notice Review (500 / 409)

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)

​Cancellation Notice Holds (422)

​Saved Cancellation Approval Needs Notice Review (500 / 409)

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

Cancellation Notice Holds (422)

Saved Cancellation Approval Needs Notice Review (500 / 409)

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