Go语言中Didit API错误处理与重试机制精要 (ZH)

理解 Didit 的速率限制针对 429 响应实施客户端限流和指数退避，利用 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset 头信息来防止服务中断。

区分错误类型区分瞬态错误（例如，网络问题、服务不可用）和永久错误（例如，无效的 API 密钥、格式错误的请求），以应用适当的重试逻辑或快速失败。

实施强大的重试机制采用结构化的重试循环，结合指数退避、抖动和最大重试次数，以优雅地处理瞬态故障，提高会话创建等关键操作的可靠性。

Didit 的开发者优先方法简化集成Didit 提供清晰的 API 文档、特定的速率限制头信息和模块化架构，使 Go 开发者能够轻松自信地构建弹性身份验证流程。

集成第三方 API 是现代应用开发的基石，身份验证也不例外。在使用 Didit 的身份平台等关键服务时，确保您的集成能够抵御网络波动、服务中断和速率限制至关重要。本指南深入探讨了专为使用 Go 语言进行的 Didit API 集成量身定制的高级错误处理和重试策略，帮助您构建健壮可靠的系统。

理解 Didit 的 API 错误格局

在实施任何重试逻辑之前，了解您可能遇到的错误类型至关重要。Didit 的 API，像许多精心设计的服务一样，通过 HTTP 状态码传达各种状态。虽然标准的 2xx 代码表示成功，但您主要会关注 4xx（客户端错误）和 5xx（服务器错误），尤其是 429（请求过多）。

Didit 的速率限制及其对您的意义

Didit 强制执行速率限制以维护 API 稳定性。这是您在集成中需要管理的关键方面。例如，GET 端点通常每个应用程序每分钟有 300 个请求的全局限制，而像 session-decision (100 rpm) 或 session-v2-create (600 rpm) 等特定端点有其自己的、可能更严格的限制。当您达到速率限制时，Didit 会返回 429 Too Many Requests 状态码，并包含有用的头信息：

• X-RateLimit-Limit: 当前窗口允许的最大请求数。
• X-RateLimit-Remaining: 当前窗口中剩余的请求数。
• X-RateLimit-Reset: 当前速率限制窗口重置的时间（以 epoch 秒为单位）。
• Retry-After:（通常包含）在进行另一次请求之前需要等待的秒数。

您的 Go 客户端应积极监控这些头信息。当 X-RateLimit-Remaining 低于某个阈值（例如，X-RateLimit-Limit 的 15%）时，您应该主动限制您的请求。忽略这些可能导致持续的 429 错误，影响您的应用程序创建验证会话或从 Didit 的身份验证或 AML 筛选等产品中检索结果的能力。

在 Go 中使用指数退避实现强大的重试策略

对于瞬态错误（例如，网络超时、临时服务不可用或 429），重试至关重要。然而，天真的重试可能会加剧问题。黄金标准是带有抖动的指数退避。

带有抖动的指数退避

指数退避意味着以指数方式增加重试之间的等待时间。抖动（添加小的随机延迟）可以防止在服务中断后许多客户端同时重试，再次压垮服务的“惊群”问题。这是一个概念性的 Go 示例：

package main

import (
	"fmt"
	"io/ioutil"
	"net/http"
	"time"
	"math/rand"
)

func callDiditAPIWithRetry(url string, maxRetries int) ([]byte, error) {
	client := &http.Client{Timeout: 10 * time.Second}
	rand.Seed(time.Now().UnixNano())

	for i := 0; i <= maxRetries; i++ {
		resp, err := client.Get(url)
		if err != nil {
			// Handle network errors (e.g., connection refused, timeout)
			fmt.Printf("Attempt %d: Network error: %v\n", i+1, err)
			if i == maxRetries {
				return nil, fmt.Errorf("failed after %d retries: %w", maxRetries, err)
			}
			sleepTime := time.Duration(1<<i)*time.Second + time.Duration(rand.Intn(1000))*time.Millisecond // Exponential backoff + jitter
			fmt.Printf("Retrying in %v...\n", sleepTime)
			time.Sleep(sleepTime)
			continue
		}
		defer resp.Body.Close()

		switch resp.StatusCode {
		case http.StatusOK:
			fmt.Printf("Attempt %d: Success!\n", i+1)
			return ioutil.ReadAll(resp.Body)
		case http.StatusTooManyRequests:
			// Respect Retry-After header if present
			retryAfter := resp.Header.Get("Retry-After")
			if retryAfter != "" {
				if sleepSeconds, err := time.ParseDuration(retryAfter + "s"); err == nil {
					fmt.Printf("Attempt %d: Rate limited. Retrying after %v.\n", i+1, sleepSeconds)
					time.Sleep(sleepSeconds)
					continue
				}
			}
			// Fallback to exponential backoff if Retry-After is missing or invalid
			fmt.Printf("Attempt %d: Rate limited (429).\n", i+1)
			if i == maxRetries {
				return nil, fmt.Errorf("rate limited after %d retries", maxRetries)
			}
			sleepTime := time.Duration(1<<i)*time.Second + time.Duration(rand.Intn(1000))*time.Millisecond
			fmt.Printf("Retrying in %v...\n", sleepTime)
			time.Sleep(sleepTime)
			continue
		case http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
			// Server-side errors that might be transient
			fmt.Printf("Attempt %d: Server error %d. Retrying.\n", i+1, resp.StatusCode)
			if i == maxRetries {
				return nil, fmt.Errorf("server error %d after %d retries", resp.StatusCode, maxRetries)
			}
			sleepTime := time.Duration(1<<i)*time.Second + time.Duration(rand.Intn(1000))*time.Millisecond
			fmt.Printf("Retrying in %v...\n", sleepTime)
			time.Sleep(sleepTime)
			continue
		default:
			// Non-retryable errors (4xx client errors, etc.)
			body, _ := ioutil.ReadAll(resp.Body)
			return nil, fmt.Errorf("non-retryable API error: %d %s, response: %s", resp.StatusCode, resp.Status, string(body))
		}
	}
	return nil, fmt.Errorf("unexpected control flow") // Should not be reached
}

func main() {
	// Example usage: Replace with actual Didit API endpoint
	// For a real integration, you'd be POSTing to /v3/session/ or similar
	// and handling the verification_url.
	apiURL := "https://verification.didit.me/health"
	data, err := callDiditAPIWithRetry(apiURL, 5)
	if err != nil {
		fmt.Println("Failed to call API:", err)
	} else {
		fmt.Println("API Response:", string(data))
	}
}

此代码片段演示了如何使用指数退避和抖动处理网络错误、429 错误（遵守 Retry-After）和常见的 5xx 错误。它还展示了对不可重试的 4xx 错误进行快速失败，这些错误通常是由于不正确的输入导致的，并且不会在重试时解决。这对于使用 Didit 模块化架构创建验证会话等操作至关重要。

实施熔断器模式

虽然重试有助于解决瞬态问题，但如果服务确实已停机，持续重试失败的服务可能会进一步使其过载或浪费资源。这就是熔断器模式发挥作用的地方。熔断器监控故障，如果故障达到一定阈值，则“打开”电路，在设定时间内阻止进一步的请求。在此期间之后，它允许进行一些测试请求，以查看服务是否已恢复。

在 Go 中，您可以使用像 sony/gobreaker 这样的库来实现此模式：

package main

import (
	"errors"
	"fmt"
	"io/ioutil"
	"net/http"
	"time"

	"github.com/sony/gobreaker"
)

var cb *gobreaker.CircuitBreaker

func init() {
	st := gobreaker.Settings{
		Name:        "DiditAPICircuitBreaker",
		MaxRequests: 3, // Allow 3 requests in half-open state
		Interval:    5 * time.Second, // Period to collect data for trip decisions
		Timeout:     10 * time.Second, // Open circuit for 10 seconds
		ReadyToTrip: func(counts gobreaker.Counts) bool {
			return counts.ConsecutiveFailures > 5 // Trip after 5 consecutive failures
		},
		OnStateChange: func(name string, from gobreaker.State, to gobreaker.State) {
			fmt.Printf("Circuit Breaker '%s' changed from %s to %s\n", name, from, to)
		},
	}
	cb = gobreaker.NewCircuitBreaker(st)
}

func callDiditAPIWithCircuitBreaker(url string) ([]byte, error) {
	body, err := cb.Execute(func() (interface{}, error) {
		resp, err := http.Get(url)
		if err != nil {
			return nil, err // Network error
		}
		defer resp.Body.Close()

		if resp.StatusCode != http.StatusOK {
			// Only count 5xx and 429 as failures for circuit breaker
			if resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= http.StatusInternalServerError {
				return nil, fmt.Errorf("API returned status %d", resp.StatusCode)
			}
			// For other 4xx errors, we might not want to trip the breaker, but still return an error
			bodyBytes, _ := ioutil.ReadAll(resp.Body)
			return nil, fmt.Errorf("non-retryable API error: %d %s, response: %s", resp.StatusCode, resp.Status, string(bodyBytes))
		}

		return ioutil.ReadAll(resp.Body)
	})

	if err != nil {
		if errors.Is(err, gobreaker.ErrOpenState) {
			return nil, fmt.Errorf("circuit breaker is open: %w", err)
		}
		return nil, err
	}

	return body.([]byte), nil
}

func main() {
	// Example usage
	apiURL := "https://verification.didit.me/health"
	for i := 0; i < 10; i++ {
		data, err := callDiditAPIWithCircuitBreaker(apiURL)
		if err != nil {
			fmt.Printf("Call %d failed: %v\n", i+1, err)
		} else {
			fmt.Printf("Call %d successful: %s\n", i+1, string(data))
		}
		time.Sleep(1 * time.Second)
	}
}

将熔断器与指数退避结合使用可确保您的应用程序保持响应，并且不会使陷入困境的外部服务过载。这在处理高容量身份验证请求时尤为重要，例如涉及 Didit 的身份验证或被动与主动活体检测的请求。

处理 Webhook 故障和异步结果

Didit 的 API 通常通过 Webhook 异步提供结果，例如，在用户完成身份验证流程后或 AML 筛选检查完成后。您的 Webhook 端点必须是健壮的。如果您的端点未能处理 Webhook（例如，返回 5xx 状态码），Didit 将重试发送 Webhook。以下几点至关重要：

• 立即确认收到： 尽快返回 2xx 状态码以表示成功收到，即使处理需要更长时间。
• 异步处理： 将 Webhook 有效负载交给后台工作者或消息队列（例如，Kafka、RabbitMQ）进行处理。这可以防止您的 Webhook 端点因 Didit 的重试而超时。
• 幂等性： 确保您的 Webhook 处理逻辑是幂等的。如果 Didit 重试并多次发送相同的 Webhook，您的系统应该只处理一次，以避免重复操作或数据不一致。
• 验证签名： 始终使用 Didit 控制台中的 Webhook Secret Key 验证 Webhook 签名，以确保请求确实源自 Didit 且未被篡改。

Didit 如何提供帮助

Didit 的设计考虑了开发者体验和可靠性，提供了固有地简化 Go 集成的高级错误处理和重试策略的功能。我们的开发者优先方法意味着清晰、全面的 API 文档、即时沙盒和简洁的 API，使集成变得简单。

• 可预测的速率限制： Didit 明确定义了全局和特定于端点的速率限制，以及标准 HTTP 头信息（X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、Retry-After），以指导您的客户端限流和退避逻辑。这种透明性使您能够为身份验证和 AML 筛选等服务构建优化的重试机制。
• 模块化架构： 我们的模块化身份原语意味着您可以构建本质上具有弹性的工作流。如果某个特定检查（例如，地址证明）遇到瞬态问题，您的整体工作流可以配置为适应或重试特定组件，而不会影响不相关的验证步骤。
• AI 原生可靠性： Didit 的 AI 原生后端专为规模和弹性而构建，最大限度地减少您将遇到的服务器端错误。这使您可以将错误处理重点放在网络和客户端问题上，而不是持续的服务中断。
• 免费核心 KYC 和灵活定价： 通过Didit 的免费套餐开始使用核心 KYC，让您可以在生产环境中彻底测试您的错误处理和重试策略，而无需预付费用。我们的按成功检查付费模式进一步使我们的成功与您的成功保持一致。

准备好开始了吗？

准备好看到 Didit 的实际效果了吗？立即获取免费演示。

通过Didit 的免费套餐免费开始验证身份。