CoverPort API and SDK are in beta. Endpoints and the embed may change without notice, and sales should be reconciled in the developer portal. Report problems to support@coverport.io.
CargoLabs Docs

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"
}
  • code is stable and safe to branch on.
  • message is 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.
  • requestId is also sent as the X-Request-Id header on every response. Include it when you contact support.

Codes

HTTPcodeMeaningWhat to do
400invalid_requestThe request is not valid. details says why.Fix the request. Do not retry as is.
400unsupported_versionCoverPort-Version is not a version of this API.Send a version listed in details.
403invalid_api_keyThe key is missing, unknown, frozen or deleted. Refused by the gateway before the API runs.Send a valid key in x-api-key.
403key_not_linkedYour key is not linked to an agent.Link one in the developer portal.
403forbiddenThe buyer or purchase belongs to another agent, or the key is not valid.Check the id, and which key you sent.
403api_not_availableThe API is off by default and not enabled for your key yet.Email api-support@coverport.io.
4xxrequest_refusedThe gateway refused the request for another reason.Check the method, path and headers.
404route_not_foundThere is no such route.Check the method and path.
404product_not_foundThe buyer cannot purchase that product from you.List the buyer's products again.
409binding_moratoriumThe product cannot be sold for those dates right now, for example during a hurricane.Try other dates, or later.
409idempotency_in_progressA request with this Idempotency-Key is still running.Wait for Retry-After, then retry with the same key.
409idempotency_outcome_unknownThe 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.
422name_requiredPOST /buyers with a new email and no name. Nothing was created.Send firstName and lastName.
422idempotency_key_reusedThis Idempotency-Key was already used with a different request. Nothing was done.Use a new key for a new request.
422invalid_answersThe insurer's checks refused the answers. details says why.Show the buyer, correct, retry.
429signup_limitYour 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.
429rate_limitedYour key went over a per-second limit (Rate limits). Always has a Retry-After header.Wait for Retry-After, then retry.
429quota_exceededYour 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, 504internal_errorSomething broke on our side, or took too long. The request may have been done.Check before retrying, then retry with a new Idempotency-Key.
502upstream_errorA CoverPort service failed or timed out. The request may have been done.Check before retrying, then retry with a new Idempotency-Key.
503idempotency_unavailableThe 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.json

For 24 hours, per API key:

You send the same key withYou get
the same body, after the first request succeededThe first response again, with the header Idempotent-Replayed: true. Nothing is done twice.
the same body, while the first request is still running409 idempotency_in_progress with Retry-After. Retry with the same key.
the same body, after the first request failed with a 5xx or never answered409 idempotency_outcome_unknown. The first request may have been done, so it is not run again.
a different body or endpoint422 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.

On this page