Safe purchases & retries
Recover uncertain requests without accidentally buying another number.
Persist before purchasing
POST /orders requires a UUID v4 Idempotency-Key header and a quoteId in its JSON body. Persist both values before sending the request.
Treat that pair as the identity of one purchase. Reusing a quote can recover its existing order; reusing a key with a different quote returns a conflict.
import { randomUUID } from "node:crypto";
const purchaseKey = randomUUID();
// Save purchaseKey and the approved quote.id in durable storage.
// Only then send POST /orders. Reuse both values on retry.Recover an uncertain response
If POST /orders times out, do not assume it failed. Retry the same request with the original saved key and quote ID.
When you already have an order ID, retrieve that order first. A successful HTTP response may contain purchasing, failed or purchase_unknown; inspect the returned record.
Do not silently create a new quote and purchase if the original outcome is unknown. That can buy a second number.
Back off on temporary errors
For 429, honor Retry-After. The response currently uses 60 seconds, but hourly or active-order account limits can last longer.
For temporary 503 or network failures, use bounded retries with backoff. Preserve purchase identity across every retry and process restart. Set a timeout for each HTTP request.
Do not blindly retry validation, authentication or balance errors. Correct the underlying issue first.
Handle expiry and stock changes
Quotes expire after two minutes and do not reserve stock. A known, rejected purchase may need a new quote, but first establish that the earlier request did not create an order.
Review the new quote price against your budget. A previous quote does not guarantee the same price or stock on a later request.