Errors
The API distinguishes two kinds of failure: request errors, where the API call itself was rejected, and job failures, where the call succeeded but a carrier did not produce a quote. They are handled differently.
Request Errors
All request errors follow one structure.
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Request contains invalid fields",
"field_errors": {
"contactPhone": ["Insured phone must be 10 digits"]
}
}
}| HTTP | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing or malformed request fields. field_errors lists every failing field, not just the first. |
| 401 | UNAUTHORIZED | Missing or invalid API key |
| 403 | FORBIDDEN | Key lacks the required scope |
| 403 | AGENCY_PAUSED | The agency is in a paused billing state; quoting is blocked |
| 403 | CARRIER_NOT_ENABLED | One or more selected carriers are not enabled for this agency |
| 404 | NOT_FOUND | The record does not exist, or belongs to another agency |
| 409 | INVALID_STATE | The request is not in a state that permits this operation |
| 429 | RATE_LIMITED | Request rate exceeded. Back off and retry. |
| 500 | INTEGRATION_ERROR | QuoteSweep encountered an internal error. Retriable. |
Job Failure Types
A job that ends without a quote carries an errorType. The request itself succeeded — read these from the status response, not from an HTTP status code.
| Value | Retriable | Description |
|---|
Declines are not errors
declined_appetite means a carrier assessed the risk and said no. Retrying will produce the same answer. Show it to the agent as a decline with the carrier's stated reason, distinct from a technical failure they might retry.
Recoverable failures need a person, not a retry
mfa_required, uwq_unanswered, and uwq_aborted mean a nearly-complete quote is waiting on agent input. Route the agent to the deep link rather than resubmitting — a new request restarts the carrier submission from the beginning. See Action Required.
Partial Runs Are Normal
A run where three of five carriers quote, one declines, and one needs MFA returns request status partial with HTTP 200. Treat partial as a successful outcome that carries detail, not as a failure state.