Reliability & Errors

Working with global company registers means dealing with instability. Registers have maintenance windows, rate limits, and unexpected downtime. Topograph abstracts this complexity, but our approach to reliability differs depending on which endpoint you use. We make deliberate trade-offs between speed and robustness.

Monitor real-time system status at status.topograph.co.

The speed vs. robustness trade-off

Same endpoint (POST /v2/company), different behavior by mode:

Mode	Priority	Strategy	Retry behavior
`mode: "prefill"`	Speed	Fail fast	Strict short timeouts. Minimal retries—if the register is slow, we return quickly rather than wait.
Verification (default)	Robustness	Deliver eventually	Longer retries—up to 1 hour for transient register outages.

The legacy POST /v2/onboarding route follows the same fast-path strategy but is deprecated; prefer mode: "prefill". See Data retrieval modes.

Retry strategies

Prefill mode (`mode: "prefill"`)

Designed for real-time user flows where latency matters most.

Timeout: Hard 10-second deadline per datapoint. Datapoints that do not finish in time fail with error code onboarding_timeout. Any partial data that arrived before the deadline is still returned.
Retries: Minimal. We do not retry transient register errors that would delay the response significantly.
Priority: Speed over completeness. Retry without mode: "prefill" if you need the datapoint the slow way.

Verification mode (default `POST /v2/company`)

Designed for back-office processes where data completeness is critical.

Timeout: Long. We accept that some requests might take minutes if the register is struggling
Retries: Exponential backoff strategies. For scheduled register maintenance or temporary outages, we may retry for up to 1 hour
Priority: Eventual success over immediate failure

Because verification requests can be long-running, we strongly recommend using webhooks to receive results asynchronously.

Error handling

Errors come back at two levels. An HTTP error status means the request itself was refused. Once a POST /v2/company request is accepted, a problem with one datapoint or document does not change the HTTP status: the response is still 200 or 201, and the item is marked failed in request.dataStatus with an error.code.

HTTP status codes

When a request is refused, the body’s error.code uses the same vocabulary as the item-level codes below.

Code	Error	Description	Action
`400`	Bad Request	Invalid parameters, data points or identifier format	Fix your request payload
`401`	Unauthorized	Invalid or missing API key	Check your credentials
`404`	Not Found	Unknown `requestId` on `GET /v2/company/{requestId}`	Check the request ID
`406`	Not Acceptable	Country not supported by search	Check coverage and pricing
`429`	Too Many Requests	You hit your rate limit	Slow down your requests
`500`	Internal Error	Server-side issue	Contact support if persistent
`503`	Service Unavailable	A search could not reach the register or took too long	Retry the search later

Datapoint and document error codes

These appear in request.dataStatus on the response and in company.updated webhooks. Each failed item carries a code, a human-readable message you can show your own users, retryable, and, when retryable, retryAfterSeconds:

"shareholders": {
  "status": "failed",
  "error": {
    "code": "source_unavailable",
    "message": "The 'handelsregister' register is temporarily unavailable. Please try again later.",
    "source": "handelsregister",
    "retryable": true,
    "retryAfterSeconds": 300
  }
}

Every error.code is listed below with its fixed retryable flag and the recommended minimum wait before you resubmit. The same list is the PublicErrorCode enum in the API reference, with the same description on every value, so a generated client can switch on it. Failed items are never charged.

`error.code`	`retryable`	`retryAfterSeconds`	Meaning	What to do
`service_unavailable`	`true`	300	Topograph could not complete the lookup because of a temporary problem on its side.	Resubmit the same request after `retryAfterSeconds`, doubling the delay on each further failure (cap at one hour).
`source_unavailable`	`true`	300	The register behind this datapoint is down, rate limiting or timing out; `error.source` names it when known.	Resubmit the same request after `retryAfterSeconds`, doubling the delay on each further failure (cap at one hour).
`processing_failed`	`true`	900	The register answered, but Topograph could not process the response; the team is alerted automatically.	Resubmit the same request after `retryAfterSeconds`, doubling the delay on each further failure (cap at one hour).
`request_cancelled`	`true`	0	The request was cancelled before this item completed.	Resubmit the same request right away.
`processing_interrupted`	`true`	0	Processing was interrupted before this item completed; no verdict was reached.	Resubmit the same request right away.
`resource_not_found`	`false`	n/a	No company exists in the register under this identifier.	Nothing to retry: the same request returns the same answer. Treat it as a final result.
`invalid_request`	`false`	n/a	The request is malformed: an unknown datapoint, a badly formatted identifier or an invalid parameter.	Correct the request before resending it; resent unchanged, it fails the same way.
`insufficient_funds`	`false`	n/a	The wallet balance does not cover the price of this request.	Top up the wallet, then resubmit.
`datapoint_not_supported`	`false`	n/a	Topograph does not return this datapoint for this country, in any mode.	Nothing to retry: the same request returns the same answer. Treat it as a final result.
`fast_source_unavailable`	`false`	n/a	The datapoint exists for this country, but not in prefill mode.	Resubmit without `mode: "prefill"`.
`authoritative_source_unavailable`	`false`	n/a	The datapoint exists for this country, but only from a non-authoritative source, which verification mode does not use.	Resubmit with `mode: "prefill"`.
`onboarding_timeout`	`false`	n/a	The datapoint did not finish within the prefill-mode deadline.	Resubmit without `mode: "prefill"`.
`no_data_available`	`false`	n/a	The register answered, but holds no data for this company and datapoint.	Nothing to retry: the same request returns the same answer. Treat it as a final result.
`no_document_available`	`false`	n/a	The requested document is not available for this company; failed document orders are not charged.	Nothing to retry: the same request returns the same answer. Treat it as a final result.
`manual_document_timeout`	`false`	n/a	A manually fulfilled document was not delivered within the expected timeframe.	Contact support@topograph.co with the request id.
`datapoint_not_applicable`	`false`	n/a	The datapoint does not exist for this entity’s legal form, for example the shareholders of a sole trader.	Nothing to retry: the same request returns the same answer. Treat it as a final result.
`account_configuration_required`	`false`	n/a	The data source needs account-specific credentials that are not configured on your account.	Store the credentials on your account (see Register credentials), then resubmit.
`budget_exceeded`	`false`	n/a	The quoted price exceeds the budget cap set on the request.	Raise or remove the budget cap on the request, then resubmit.
`balance_negative`	`false`	n/a	The wallet balance is below zero; every request is refused until it is topped up.	Top up the wallet, then resubmit.

retryable: false means the same request returns the same answer: do not retry it, and do not alert on the codes that are a legitimate “nothing to report” (see Retrieve a company). Switch on error.code or on error.retryable, never on error.message; messages change, codes and flags are stable.

Retrying a retryable item

Five codes are retryable: service_unavailable, source_unavailable, processing_failed, request_cancelled and processing_interrupted. For those:

A retry is a new POST /v2/company with the same body, or with only the failed datapoints. Polling GET /v2/company/{requestId} reads the existing result; it never re-runs a failed item.
Wait at least retryAfterSeconds before the first retry. Double the delay on each further failure, add a little jitter so queued retries do not all fire together, and cap the delay at one hour.
Give up after 24 hours. Check status.topograph.co for an ongoing incident, and contact support with the requestId if nothing is posted there.

The delay is guidance about how long the cause usually lasts, not a promise that it is fixed by then. In verification mode (the default) we have already retried the register for up to an hour before returning source_unavailable, so a quick retry rarely helps. In prefill mode the failure is fail-fast: resubmitting without mode: "prefill" is usually the better move. HTTP 429 is different: it carries a Retry-After header, and Concurrency & Backfills explains how to retry it while keeping capacity for live traffic.

Handling “in progress” status

For the verification endpoint, data retrieval is asynchronous. You will initially receive a 200 OK response with data status set to in_progress.

{
  "request": {
    "dataStatus": {
      "dataPoints": {
        "company": {
          "status": "in_progress"
        }
      }
    }
  }
}

Do not treat this as an error. It means we have accepted your request and are working on it (including handling any necessary retries). Wait for the webhook. Most datapoints resolve within the retry windows described above. A small number are manually delivered and typically take 1–3 business days. These stay in_progress during that time and do not hold a concurrency slot.

Handling register instability

If you receive a failed status in your webhook payload with code: "source_unavailable":

Prefill mode: This is usually final for that request. Ask the user to enter details manually, or resubmit without mode: "prefill".
Verification mode: We tried for up to 1 hour and still could not reach the register, often a prolonged outage (for example weekend maintenance). Resubmit after retryAfterSeconds, backing off as described above.

Breaking changes in a register

Registries occasionally introduce breaking changes such as new API versions, schema modifications, authentication updates, or structural changes to their data formats. These changes can temporarily disrupt data retrieval until we adapt our integration.

Our response strategy

We maintain strong monitoring and agile development processes to detect and respond to registry changes quickly:

24-hour recovery target: We aim to resolve breaking changes from registries within 24 business hours of detection
Proactive monitoring: Our systems continuously monitor register responses and API behavior to detect anomalies early
Rapid adaptation: When breaking changes occur, our team prioritizes fixes to restore service as quickly as possible

What this means for you

Temporary disruptions: If a register has a breaking change, you may see more datapoints fail with source_unavailable until we adapt. Note that you never pay for failed requests!
Automatic recovery: Once we’ve updated our integration, service will resume automatically, no action required on your end
Status updates: Check status.topograph.co for real-time updates during incidents.

If you experience persistent errors for a specific country, please contact support so we can assist in the most efficient way.

Getting Started

AI Agents

Integration Guides

Core Features

Behavior & Operations

Reliability & Errors

The speed vs. robustness trade-off

Retry strategies

Prefill mode (`mode: "prefill"`)

Verification mode (default `POST /v2/company`)

Error handling

HTTP status codes

Datapoint and document error codes

Retrying a retryable item

Handling “in progress” status

Handling register instability

Breaking changes in a register

Our response strategy

What this means for you

​The speed vs. robustness trade-off

​Retry strategies

​Prefill mode (mode: "prefill")

​Verification mode (default POST /v2/company)

​Error handling

​HTTP status codes

​Datapoint and document error codes

​Retrying a retryable item

​Handling “in progress” status

​Handling register instability

​Breaking changes in a register

​Our response strategy

​What this means for you

The speed vs. robustness trade-off

Retry strategies

Prefill mode (`mode: "prefill"`)

Verification mode (default `POST /v2/company`)

Error handling

HTTP status codes

Datapoint and document error codes

Retrying a retryable item

Handling “in progress” status

Handling register instability

Breaking changes in a register

Our response strategy

What this means for you