Skip to content
Bloomfilter Bloomfilter

Async Provisioning

Most domain registrations complete instantly and return 201 Created. But sometimes the upstream registry takes longer. When this happens, Bloomfilter returns 202 Accepted with a job ID for polling.

When does async happen?

Section titled “When does async happen?”
  • Premium domains — registry may take extra time to process
  • Registry congestion — high-traffic periods at the TLD registry
  • Timeout fallback — if the upstream registry doesn’t respond within the internal timeout

The 202 response

Section titled “The 202 response”
{
  "status": "pending",
  "jobId": "01JMXYZ...",
  "message": "Registration is being processed asynchronously",
  "poll_url": "/domains/status/01JMXYZ...",
  "poll_interval_ms": 2000
}

Polling for status

Section titled “Polling for status”
Terminal window
curl https://api.bloomfilter.xyz/domains/status/01JMXYZ...

Pending/processing (202)

Section titled “Pending/processing (202)”
{
  "id": "01JMXYZ...",
  "status": "processing",
  "type": "domain_registration",
  "domain": "example.io",
  "years": 1,
  "walletAddress": "0x1234...abcd",
  "result": null,
  "createdAt": "2026-02-21T12:00:00Z",
  "updatedAt": "2026-02-21T12:00:05Z",
  "poll_interval_ms": 2000
}

Completed (200)

Section titled “Completed (200)”
{
  "id": "01JMXYZ...",
  "status": "completed",
  "type": "domain_registration",
  "domain": "example.io",
  "years": 1,
  "walletAddress": "0x1234...abcd",
  "result": {
    "transactionId": "tx_abc123",
    "domain": "example.io",
    "years": 1,
    "price_usd": "34.99",
    "expiresAt": "2027-02-21T00:00:00Z",
    "nameservers": ["ns1.bloomfilter.xyz", "ns2.bloomfilter.xyz"],
    "dnsRecords": []
  },
  "createdAt": "2026-02-21T12:00:00Z",
  "updatedAt": "2026-02-21T12:00:10Z"
}

Failed (500 with status “failed”)

Section titled “Failed (500 with status “failed”)”
{
  "id": "01JMXYZ...",
  "status": "failed",
  "type": "domain_registration",
  "domain": "example.io",
  "years": 1,
  "walletAddress": "0x1234...abcd",
  "result": null,
  "errorMessage": "Registration failed: domain became unavailable during processing",
  "createdAt": "2026-02-21T12:00:00Z",
  "updatedAt": "2026-02-21T12:00:15Z"
}

Polling implementation

Section titled “Polling implementation”
async function waitForJob(jobId: string): Promise<any> {
  const maxAttempts = 30;
  let attempts = 0;


  while (attempts < maxAttempts) {
    const { data } = await axios.get(
      `https://api.bloomfilter.xyz/domains/status/${jobId}`
    );


    if (data.status === "completed") return data.result;
    if (data.status === "failed") throw new Error(data.errorMessage);


    // Wait the recommended interval before polling again
    await new Promise((r) => setTimeout(r, data.poll_interval_ms ?? 2000));
    attempts++;
  }


  throw new Error("Job polling timed out");
}