Errors
One error shape. A stable code to branch on, every problem listed, and an id for support.
The shape
Every error has the same body:
{
"error": {
"code": "invalid_request",
"message": "Some answers are missing or not valid.",
"details": [
"answers: question 286 (VIN #) is required",
"units: Too big: expected number to be <=127"
]
},
"requestId": "6c1f0e7a-2d4b-4b8e-9a51-0f3c2d1e4b5a"
}codeis stable and safe to branch on.messageis for people and may change.details, when present, lists every problem found, each starting with the field or question it is about. Fix them all and retry once.requestIdis also sent as theX-Request-Idheader on every response. Include it when you contact support.
Codes
| HTTP | code | Meaning | What to do |
|---|---|---|---|
| 400 | invalid_request | The request is not valid. details says why. | Fix the request. Do not retry as is. |
| 400 | unsupported_version | CoverPort-Version is not a version of this API. | Send a version listed in details. |
| 403 | invalid_api_key | The key is missing, unknown, frozen or deleted. Refused by the gateway before the API runs. | Send a valid key in x-api-key. |
| 403 | key_not_linked | Your key is not linked to an agent. | Link one in the developer portal. |
| 403 | forbidden | The buyer or purchase belongs to another agent, or the key is not valid. | Check the id, and which key you sent. |
| 403 | api_not_available | The API is off by default and not enabled for your key yet. | Email api-support@coverport.io. |
| 4xx | request_refused | The gateway refused the request for another reason. | Check the method, path and headers. |
| 404 | route_not_found | There is no such route. | Check the method and path. |
| 404 | product_not_found | The buyer cannot purchase that product from you. | List the buyer's products again. |
| 409 | binding_moratorium | The product cannot be sold for those dates right now, for example during a hurricane. | Try other dates, or later. |
| 409 | idempotency_in_progress | A request with this Idempotency-Key is still running. | Wait for Retry-After, then retry with the same key. |
| 409 | idempotency_outcome_unknown | The first request with this Idempotency-Key failed on our side or never answered, so it may have been done. It will not be run again. | Check (GET /purchases, GET /buyers) before trying again, with a new key. |
| 422 | name_required | POST /buyers with a new email and no name. Nothing was created. | Send firstName and lastName. |
| 422 | idempotency_key_reused | This Idempotency-Key was already used with a different request. Nothing was done. | Use a new key for a new request. |
| 422 | invalid_answers | The insurer's checks refused the answers. details says why. | Show the buyer, correct, retry. |
| 429 | signup_limit | Your key signed up its limit of buyers for the hour or day (30 an hour, 100 a day). | Wait for Retry-After, or ask us to raise it. |
| 429 | rate_limited | Your key went over a per-second limit (Rate limits). Always has a Retry-After header. | Wait for Retry-After, then retry. |
| 429 | quota_exceeded | Your key used its daily quota. It resets at 00:00 UTC. No Retry-After. | Do not retry before 00:00 UTC. Email api-support@coverport.io to raise it. |
| 500, 504 | internal_error | Something broke on our side, or took too long. The request may have been done. | Check before retrying, then retry with a new Idempotency-Key. |
| 502 | upstream_error | A CoverPort service failed or timed out. The request may have been done. | Check before retrying, then retry with a new Idempotency-Key. |
| 503 | idempotency_unavailable | The Idempotency-Key could not be checked. Nothing was done. | Retry with the same key. |
New codes may be added. For a code you do not recognise, act on the HTTP status.
Retrying safely
Every GET is safe to retry.
POST /quotes makes a new payment page each time, and POST /buyers can email the buyer. To retry them safely, send an Idempotency-Key header with a value unique to the thing you are doing (a UUID, or your own order or sign-up id, up to 255 characters, no spaces):
curl -X POST "https://api.coverport.io/api/quotes" \
-H "x-api-key: $COVERPORT_API_KEY" \
-H "CoverPort-Version: 2026-11-20" \
-H "Idempotency-Key: order-8812-quote" \
-H "Content-Type: application/json" \
-d @quote.jsonFor 24 hours, per API key:
| You send the same key with | You get |
|---|---|
| the same body, after the first request succeeded | The first response again, with the header Idempotent-Replayed: true. Nothing is done twice. |
| the same body, while the first request is still running | 409 idempotency_in_progress with Retry-After. Retry with the same key. |
the same body, after the first request failed with a 5xx or never answered | 409 idempotency_outcome_unknown. The first request may have been done, so it is not run again. |
| a different body or endpoint | 422 idempotency_key_reused. Nothing is done. |
A key never makes the work happen twice. After a 4xx nothing was done and the key is free again: fix the request and retry with the same key. After a 5xx, or a request that timed out or never answered, the work may or may not have happened, and the key will only answer 409 idempotency_outcome_unknown. Check first: for a quote, GET /purchases?quoteId= once the buyer has paid, or simply send the buyer the newer quote, since an unpaid payment page expires; for a sign-up, GET /buyers?email=. Then use a new key if you still need to. The order of fields in the body does not matter.
Without the header, a retried POST /quotes makes a second payment page (an unpaid one expires; send the buyer only the latest paymentUrl), and a retried POST /buyers after a 5xx may email the buyer again.