Skip to main content
Official registers go offline. They also change. Give Topograph time to handle both and deliver the missing data through your original request.

​
Built for outages. Ready for change.

Topograph retries after temporary register outages. When a register changes, Topograph's self-healing system updates its own connection to the register and retries. Topograph delivers data through the same request. Topograph retries during temporary outages. During maintenance, downtime, or rate limiting, Topograph gives the register time to recover. When it responds again, Topograph can retrieve your data on an eligible retry. Topograph adapts to register changes. When a register changes its website or data format, Topograph’s self-healing system diagnoses the problem and develops a fix for its own connection to that register. After the fix is deployed, Topograph retries with its updated connection. Your application does not need to change or resubmit the request. You choose how long to wait. We handle the recovery. Both paths keep eligible items in the original request, so your team does not need to restart the check or resubmit successful items. A longer retry window gives the register and our self-healing system more time to restore delivery. Recovery is not guaranteed within that window; unresolved items finish with an error you can handle.

​
When to use automatic retries

  • KYB checks and back-office reviews: let temporary failures recover without sending a case back to your team or customer.
  • Scheduled and overnight verification: give register maintenance, rate limits, and intermittent outages time to clear.
  • Incident recovery: let an open request benefit from a fix as soon as a later retry uses it.
For a form that needs an immediate answer, use prefill mode instead. Automatic retries are available only in verification mode, which is the default.

​
Configure your retry window

This example allows retries over a six-hour window. Omitting mode selects verification mode.
Choose a window that fits how long your business process can wait. These are examples, not recovery-time guarantees: The value must be an integer between 60 and 172800, inclusive. Values outside this range, including 0, are rejected with HTTP 400. Omit the option to keep normal retrieval behavior without an additional request-level retry window. The option cannot be added to a request after it has been created.

​
Follow the original request

  1. Submit the POST once and save the returned request.requestId.
  2. Poll GET /v2/company/{requestId} or process company.updated webhooks. An item awaiting an automatic retry stays in_progress; successful items remain available and are not retrieved again.
  3. Handle each item when its status becomes succeeded or failed. A webhook can contain partial results, so inspect request.dataStatus rather than treating the first webhook as completion of the whole request.
Do not submit another POST while an item is in_progress. Topograph is already handling its retries. A new POST creates a separate request; polling reads the current one.
See Billing during automatic retries for how the original request is settled.

​
When retries run and stop

The window starts when request processing begins. It includes the initial attempt, time spent retrieving other items, and waits between attempts. Despite its name, maxRetryDelaySeconds is the total retry window, not the delay between attempts. Retries wait until all items in the current attempt have finished. The delay increases between attempts and includes a random variation to spread out traffic. The schedule depends on the window and the error; there is no fixed interval or guaranteed number of attempts. A deployment makes a fix available to subsequent attempts. It does not force an immediate retry or extend your chosen window. The window limits when another attempt can start. It does not cancel an attempt already running or guarantee that the request finishes within that time. A slow initial attempt can consume the entire window without leaving time for a retry. Once no further retry is scheduled, an unsuccessful item becomes failed with its error details. An ineligible failure can become failed before the window ends. A successful item is returned as soon as it is available.

​
Which failures qualify

Only errors marked retryable: true can qualify, and that flag alone does not guarantee an automatic retry. For document retrieval and other operations that can place a register order, Topograph retries only when it can confirm no order was submitted. An uncertain outcome is reported as failed rather than risking a duplicate order. Permanent errors such as resource_not_found, no_data_available, and invalid_request are not retried. Neither are graph, the legacy companyProfile datapoint, or manually delivered items. The option is available only in verification mode. Combining it with mode: "prefill", X-Topograph-No-Cache, or agenticEnrichment is rejected with HTTP 400.
Request manual items separately when you want automatic items to retry promptly. A manual item can take days and delay the next attempt for other items in the same request, consuming their retry window.

​
After a final failure

maxRetryDelaySeconds and retryAfterSeconds serve different purposes: If an item ultimately fails with retryAfterSeconds: 300, wait at least another 5 minutes before resubmitting it. The response field does not define the automatic retry schedule or extend the original window. Check status.topograph.co for an ongoing incident. For the full list of error codes and how to handle them, see Reliability & Errors.