Skip to main content
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

EndpointPriorityStrategyRetry Behavior
Onboarding DataSpeedFail fastMinimal retries. If the register is slow, we prioritize returning quickly over waiting for the data.
Verification DataRobustnessDeliver eventuallyAggressive retries. We prefer to deliver data late (up to 1 hour of retries) rather than not deliver at all.

​
Retry strategies

​
Onboarding data (/v2/onboarding)

Designed for real-time user flows where latency matters most.
  • Timeout: Strict short timeouts (typically < 10s)
  • Retries: Minimal. We do not retry transient register errors that would delay the response significantly
  • Priority: Speed over completeness

​
Verification data (/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

When things go wrong, we provide standardized error codes. However, the meaning of an error can depend on the endpoint context.

​
Common error codes

CodeErrorDescriptionAction
400Bad RequestInvalid parameters or data pointsFix your request payload
401UnauthorizedInvalid or missing API keyCheck your credentials
402Payment RequiredInsufficient creditsTop up your account balance
404Not FoundCompany not found in the sourceVerify the ID or search again
406Not AcceptableCountry/feature not supportedCheck our coverage map
429Too Many RequestsYou hit your rate limitSlow down your requests
500Internal ErrorServer-side issueContact support if persistent
503Service UnavailableUpstream register failureOnboarding: Final failure. Verification: We are already retrying for you

​
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": {
        "companyProfile": {
          "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.

​
Handling register instability

If you receive a failed status in your webhook payload with an error like “register unavailable”:
  1. Onboarding data: This is final. Ask the user to enter details manually or try again later.
  2. Verification data: This means we tried for up to 1 hour and still couldn’t reach the register. This usually indicates a prolonged outage (e.g., weekend maintenance). You can retry the request later.

​
Registry breaking changes

Government registers occasionally introduce breaking changes—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 introduces a breaking change, you may see increased error rates or 503 Service Unavailable responses until we adapt
  • 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 that last longer than 24 business hours, please contact support. This helps us identify issues we may not have detected yet.