All Apps
Menu

API Connection Issues

Download adress details

API Connection Issues

Address Details relies on external API connections to provide comprehensive address and building information. This guide covers troubleshooting API connectivity issues, authentication problems, and service disruptions.

API Connection Architecture

External API Dependencies

Address Details integrates with multiple external APIs:

  1. BAG Registry API - Official Dutch address and building data
  2. Google Maps Platform APIs - Mapping, geocoding, and location services
  3. Q-Team Authentication Services - License validation and entitlement management
  4. Power Automate Webhooks - Event-driven automation integration

Connection Requirements

  • HTTPS/TLS 1.2+ - Secure connections for all API communications
  • Internet Access - Direct or proxy-based internet connectivity
  • DNS Resolution - Proper domain name resolution for API endpoints
  • Firewall Configuration - Appropriate firewall rules for API traffic

BAG Registry API Connection Issues

Common BAG API Problems

  1. Connection Timeout Errors

Symptoms: - Address validation fails with timeout messages - Long delays in building information retrieval - Intermittent connection failures

Diagnostic Steps: ```powershell # Test BAG API connectivity Test-NetConnection -ComputerName api.bag.kadaster.nl -Port 443

# Test DNS resolution nslookup api.bag.kadaster.nl

# Test HTTP response curl -I https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/ ```

Common Causes: - Network connectivity issues - Corporate firewall blocking API endpoints - DNS resolution problems - BAG service maintenance or outages

Solutions: - Verify internet connectivity and DNS settings - Check firewall rules and whitelist BAG API domains - Configure proxy settings if required - Check BAG service status at status.kadaster.nl

  1. Authentication Failures

Error Messages: - "HTTP 401 Unauthorized" - "Invalid API key" - "Authentication credentials expired"

Troubleshooting: ```al // Test BAG API credentials procedure TestBAGAuthentication(): Boolean var HttpClient: HttpClient; HttpRequest: HttpRequestMessage; HttpResponse: HttpResponseMessage; BAGSetup: Record \"QTEAM BAG Setup\"; begin BAGSetup.Get(); HttpRequest.SetRequestUri('https://api.bag.kadaster.nl/lvbag/individuelebevragingen/v2/'); HttpRequest.Headers.Add('X-Api-Key', BAGSetup.GetAPIKey());

if HttpClient.Send(HttpRequest, HttpResponse) then\n exit(HttpResponse.IsSuccessStatusCode())\n else\n exit(false);\n end;\n ``\n \n **Resolution Steps:**\n - Verify API key is correct and active\n - Check API subscription status with Kadaster\n - Ensure API key has appropriate permissions\n - Renew expired credentials as needed\n\n3. **Rate Limiting Issues**\n \n **Symptoms:**\n - \"HTTP 429 Too Many Requests\" errors\n - Temporary blocks on API access\n - Delayed response times\n \n **Monitoring:**\n `al\n // Monitor API usage rates\n procedure MonitorBAGAPIUsage()\n var\n APIUsageLog: Record \"QTEAM API Usage Log\";\n RequestCount: Integer;\n begin\n APIUsageLog.SetRange(\"API Service\", 'BAG');\n APIUsageLog.SetRange(\"Request Time\", CurrentDateTime - 3600000, CurrentDateTime);\n RequestCount := APIUsageLog.Count();\n \n if RequestCount > 1000 then // Example threshold\n Message('Warning: High API usage detected');\n end;\n `\n \n **Mitigation Strategies:**\n - Implement request queuing and throttling\n - Cache frequently accessed data\n - Optimize query patterns to reduce API calls\n - Consider upgrading to higher rate limit tiers\n\n### BAG API Service Outages\n\n1. **Detecting Service Issues**\n \n **Automated Monitoring:**\n `al\n // Health check for BAG API availability\n procedure CheckBAGServiceHealth(): Boolean\n var\n HttpClient: HttpClient;\n HttpRequest: HttpRequestMessage;\n HttpResponse: HttpResponseMessage;\n begin\n HttpRequest.SetRequestUri('https://api.bag.kadaster.nl/health');\n \n if HttpClient.Send(HttpRequest, HttpResponse) then\n exit(HttpResponse.IsSuccessStatusCode())\n else\n exit(false);\n end;\n `\n \n **Service Status Resources:**\n - Official BAG service status page\n - Kadaster maintenance announcements\n - Community forums and social media\n - Q-Team Solutions service alerts\n\n2. **Handling Service Disruptions**\n \n **Fallback Strategies:**\n `al\n // Implement graceful degradation\n procedure ValidateAddressWithFallback(Address: Text): Boolean\n var\n ValidationResult: Boolean;\n begin\n // Try primary BAG API\n ValidationResult := ValidateWithBAGAPI(Address);\n \n if not ValidationResult then begin\n // Fall back to cached data\n ValidationResult := ValidateWithCache(Address);\n \n if not ValidationResult then\n // Allow manual override with warning\n ValidationResult := AllowManualOverride(Address);\n end;\n \n exit(ValidationResult);\n end;\n `\n \n **User Communication:**\n - Display service status notifications\n - Provide alternative validation methods\n - Queue operations for retry when service recovers\n - Maintain transparency about service limitations\n\n## Google Maps API Connection Issues\n\n### Authentication and Authorization Problems\n\n1. **Invalid API Key Errors**\n \n **Common Error Messages:**\n - \"The provided API key is invalid\"\n - \"API key not found\"\n - \"Request denied\"\n \n **Validation Process:**\n `javascript\n // Test Google Maps API key\n async function testGoogleMapsAPIKey(apiKey) {\n const testUrl = https://maps.googleapis.com/maps/api/geocode/json?address=Amsterdam&key=${apiKey};\n \n try {\n const response = await fetch(testUrl);\n const data = await response.json();\n \n return data.status === 'OK';\n } catch (error) {\n console.error('API key test failed:', error);\n return false;\n }\n }\n `\n \n **Resolution Steps:**\n - Verify API key in Google Cloud Console\n - Check API key restrictions and permissions\n - Ensure required APIs are enabled\n - Verify billing account is active\n\n2. **API Restrictions and Limitations**\n \n **Common Restriction Issues:**\n - HTTP referrer restrictions blocking requests\n - IP address restrictions preventing access\n - API-specific restrictions limiting functionality\n \n **Configuration Review:**\n `javascript\n // Check API key restrictions\n const validateAPIKeyRestrictions = {\n httpReferrers: ['yourdomain.com/*', 'localhost/*'],\n apis: ['geocoding', 'maps-javascript-api', 'places-api'],\n ipAddresses: ['192.168.1.0/24'] // if using IP restrictions\n };\n `\n \n **Best Practices:**\n - Use appropriate restriction types for deployment\n - Regularly review and update restrictions\n - Test API access from production environment\n - Monitor for restriction-related errors\n\n### Quota and Billing Issues\n\n1. **Quota Exceeded Errors**\n \n **Error Responses:**\n `json\n {\n \"error_message\": \"The provided API key has exceeded the daily quota\",\n \"results\": [],\n \"status\": \"OVER_DAILY_LIMIT\"\n }\n `\n \n **Monitoring and Alerting:**\n `al\n // Monitor Google Maps API usage\n procedure MonitorGoogleMapsUsage()\n var\n GoogleMapsUsage: Record \"Google Maps API Usage\";\n DailyUsage: Integer;\n begin\n GoogleMapsUsage.SetRange(\"Date\", Today);\n GoogleMapsUsage.CalcSums(\"Request Count\");\n DailyUsage := GoogleMapsUsage.\"Request Count\";\n \n if DailyUsage > 24000 then // 80% of 30,000 daily limit\n NotifyAdministrators('Google Maps quota warning');\n end;\n `\n \n **Quota Management:**\n - Set up billing alerts in Google Cloud\n - Monitor usage patterns and trends\n - Implement usage-based rate limiting\n - Consider API usage optimization\n\n2. **Billing and Payment Issues**\n \n **Common Problems:**\n - Credit card expiration or payment failure\n - Billing account suspended\n - Budget limits exceeded\n \n **Resolution:**\n - Update payment methods in Google Cloud\n - Review and adjust budget settings\n - Contact Google Cloud support for billing issues\n - Implement cost monitoring and controls\n\n## Network and Infrastructure Issues\n\n### Firewall and Proxy Configuration\n\n1. **Corporate Firewall Issues**\n \n **Required Firewall Rules:**\n `\n # BAG Registry API\n Allow HTTPS (443) to *.kadaster.nl\n Allow HTTPS (443) to *.pdok.nl\n \n # Google Maps Platform\n Allow HTTPS (443) to *.googleapis.com\n Allow HTTPS (443) to *.google.com\n Allow HTTPS (443) to *.gstatic.com\n \n # Q-Team Services\n Allow HTTPS (443) to *.q-teamsolutions.com\n `\n \n **Testing Connectivity:**\n `powershell\n # Test API endpoint access\n Test-NetConnection -ComputerName maps.googleapis.com -Port 443\n Test-NetConnection -ComputerName api.bag.kadaster.nl -Port 443\n \n # Test with curl\n curl -v https://maps.googleapis.com/maps/api/js\n curl -v https://api.bag.kadaster.nl/health\n `\n\n2. **Proxy Server Configuration**\n \n **Proxy Settings for Business Central:**\n `al\n // Configure proxy for HTTP requests\n procedure ConfigureProxySettings(var HttpClient: HttpClient)\n var\n ProxySettings: Record \"Proxy Settings\";\n begin\n if ProxySettings.Get() then begin\n HttpClient.SetProxy(ProxySettings.\"Proxy URL\");\n if ProxySettings.\"Requires Authentication\" then\n HttpClient.SetProxyCredentials(ProxySettings.Username, ProxySettings.Password);\n end;\n end;\n `\n \n **Proxy Authentication:**\n - Configure proxy credentials securely\n - Test proxy connectivity independently\n - Verify proxy supports HTTPS traffic\n - Consider proxy timeout settings\n\n### SSL/TLS and Certificate Issues\n\n1. **Certificate Validation Problems**\n \n **Common Certificate Errors:**\n - Certificate chain validation failures\n - Expired or invalid certificates\n - Certificate authority not trusted\n \n **Diagnostic Commands:**\n `powershell\n # Check certificate details\n openssl s_client -connect api.bag.kadaster.nl:443 -showcerts\n openssl s_client -connect maps.googleapis.com:443 -showcerts\n \n # Verify certificate chain\n curl -v --cacert ca-bundle.crt https://api.bag.kadaster.nl\n `\n \n **Resolution:**\n - Update certificate authority bundles\n - Verify system date and time accuracy\n - Check for corporate certificate policies\n - Test from different network locations\n\n2. **TLS Version and Cipher Support**\n \n **TLS Requirements:**\n - TLS 1.2 minimum for most APIs\n - TLS 1.3 preferred for enhanced security\n - Strong cipher suite support required\n \n **Testing TLS Configuration:**\n `powershell\n # Test TLS version support\n nmap --script ssl-enum-ciphers -p 443 api.bag.kadaster.nl\n \n # Test with specific TLS version\n curl --tlsv1.2 -v https://maps.googleapis.com\n `\n\n## Troubleshooting Tools and Techniques\n\n### Network Diagnostic Tools\n\n1. **Built-in Connection Testing**\n `al\n // Comprehensive API connectivity test\n procedure RunConnectivityDiagnostics(): Text\n var\n DiagnosticResults: Text;\n BAGConnected, GoogleMapsConnected, AuthConnected: Boolean;\n begin\n BAGConnected := TestBAGAPIConnection();\n GoogleMapsConnected := TestGoogleMapsConnection();\n AuthConnected := TestAuthenticationService();\n \n DiagnosticResults := 'API Connectivity Test Results:\\n';\n DiagnosticResults += 'BAG API: ' + Format(BAGConnected) + '\\n';\n DiagnosticResults += 'Google Maps: ' + Format(GoogleMapsConnected) + '\\n';\n DiagnosticResults += 'Authentication: ' + Format(AuthConnected);\n \n exit(DiagnosticResults);\n end;\n `\n\n2. **External Monitoring Services**\n - Use uptime monitoring services for API endpoints\n - Set up alerts for service degradation\n - Monitor response times and availability\n - Track error rates and patterns\n\n### Performance Monitoring\n\n1. **Response Time Tracking**\n `al\n // Monitor API response times\n procedure TrackAPIPerformance(APIName: Text; ResponseTime: Integer)\n var\n PerformanceLog: Record \"API Performance Log\";\n begin\n PerformanceLog.Init();\n PerformanceLog.\"API Name\" := APIName;\n PerformanceLog.\"Response Time\" := ResponseTime;\n PerformanceLog.\"Timestamp\" := CurrentDateTime;\n PerformanceLog.Insert();\n \n if ResponseTime > 5000 then // 5 second threshold\n LogPerformanceAlert(APIName, ResponseTime);\n end;\n ``\n\n2. Error Rate Analysis\n - Track API error rates over time\n - Identify patterns in connection failures\n - Correlate errors with system changes\n - Generate performance reports\n\n## Escalation and Support Procedures\n\n### When to Escalate\n\n1. Immediate Escalation Required:\n - Complete loss of API connectivity\n - Authentication failures affecting all users\n - Data corruption due to API issues\n - Security-related connection problems\n\n2. Standard Escalation Process:\n - Internal IT support for network/firewall issues\n - Q-Team Solutions for Address Details specific problems\n - API provider support for service-specific issues\n - Vendor support for infrastructure problems\n\n### Information to Collect\n\n1. Diagnostic Information:\n - Exact error messages and codes\n - Network trace and connectivity test results\n - API response headers and status codes\n - System configuration and environment details\n\n2. Reproduction Steps:\n - Detailed steps to reproduce the issue\n - Frequency and timing of problems\n - Affected users or processes\n - Recent system or configuration changes\n\nBy following these troubleshooting procedures and implementing proper monitoring, API connection issues can be quickly identified, diagnosed, and resolved, ensuring reliable operation of Address Details functionality.