Idempotency and retries
POST /v1/estimates and POST /v1/estimates/{id}/follow-up need an Idempotency-Key header. Use a new random value of 1 to 64 characters, such as a UUID, for each new request.
How Hometown treats a key
| Case | Answer |
|---|---|
| A new key | Hometown runs the request and keeps its answer for 24 hours. A 400, 402, 413, 415, validation_failed, 429 or 5xx answer is not kept, so the same key works again. |
| The same key and the same body | The stored answer, with Idempotent-Replayed: true. No credits are spent again. |
| The same key while the first request runs | 409 idempotency_conflict. Wait and retry. |
| The same key with a different body | 422 idempotency_key_reused. |
When to retry
- After a network error or a timeout, send the same request with the same key.
- After 429 or 503, wait the seconds in
Retry-After, then send it again with the same key. - After an answer that is not kept, correct the request if needed and reuse the key. After any other 4xx, use a new key.