Retrying safely

Networks fail. A request can time out after HighQube has already done the work, so you can't always tell whether it went through. Here is when it's safe to send a request again.

Reads: always safe

Searches, lookups, listing quotes and downloads don't change anything, so you can send them again as often as you need.

Creating a quote: safe with an idempotency key

POST /rate-search/export with a customer_id files a quote. Sending it twice files two quotes, unless you add an Idempotency-Key header:

curl "https://api-dev.highqube.ai/rate-search/export" \
  -H "Authorization: Bearer $HIGHQUBE_API_KEY" \
  -H "Idempotency-Key: GLF-PO-48213" \
  -H "Content-Type: application/json" \
  -d '{"isSelectedAll": true, "customer_id": 2, "routes": [{"origin": "USCHI", "destination": "CNSGH"}], "containerSizes": ["40HC"]}' \
  -o quote.xlsx

Choose a new key for each quote: a UUID, or something from your own system such as an order number.
If you get no answer, send the same request with the same key. No second quote is filed. You get the first quote's workbook back, with the header Idempotent-Replayed: true.
The same key with a different request is refused with 422 idempotency_key_reused, so a reused key can never quietly return the wrong quote.
A key can be up to 255 visible ASCII characters, with no spaces.

When to retry

Response	Retry?
Timeout or connection error	Yes. Reads as they are, quote exports with the same idempotency key.
`429 rate_limited`	Yes, after `Retry-After` seconds.
`502`, `503`	Yes, after a short wait. Wait longer each time: 1, 2, 4, 8 seconds.
`400`, `422`	No. Fix the request first.
`401`, `403`	No. The key or its permissions need changing. See Errors.

Rate limits

Changelog