Blog · 6 de març del 2026

Gestió d'Errors i Reintents de l'API de Didit a Go: Guia Completa (CA)

Integrar-se amb l'API de Didit a Go requereix una gestió sofisticada d'errors i estratègies de reintent. Aquesta guia explora les millors pràctiques, des de la comprensió dels límits de velocitat de Didit fins als codis d'error.

Per Didit6 de març del 2026Actualitzat el 21 de maig del 2026

Comprèn els Límits de Velocitat de Didit Implementa una limitació per part del client i un backoff exponencial per a respostes 429, utilitzant les capçaleres X-RateLimit-Limit, X-RateLimit-Remaining i X-RateLimit-Reset per evitar la interrupció del servei.

Diferencia els Tipus d'Error Distingeix entre errors transitoris (per exemple, problemes de xarxa, indisponibilitat del servei) i errors permanents (per exemple, claus d'API no vàlides, sol·licituds mal formades) per aplicar la lògica de reintent adequada o fallar ràpidament.

Implementa Mecanismes de Reintent Robustos Utilitza bucles de reintent estructurats amb backoff exponencial, jitter i un nombre màxim d'intents per gestionar els errors transitoris de manera elegant, millorant la fiabilitat de les operacions crítiques com la creació de sessions.

L'enfocament de Didit centrat en el desenvolupador simplifica la integració Didit proporciona documentació clara de l'API, capçaleres de límit de velocitat específiques i una arquitectura modular, permetent als desenvolupadors de Go construir fluxos de verificació d'identitat resilients amb facilitat i confiança.

La integració d'APIs de tercers és una pedra angular del desenvolupament d'aplicacions modernes, i la verificació d'identitat no n'és una excepció. Quan es treballa amb serveis crítics com la plataforma d'identitat de Didit, és fonamental assegurar que la vostra integració sigui resilient a les fluctuacions de la xarxa, les interrupcions del servei i els límits de velocitat. Aquesta guia aprofundeix en la gestió avançada d'errors i les estratègies de reintent específicament adaptades per a les integracions de l'API de Didit utilitzant Go, ajudant-vos a construir sistemes robustos i fiables.

Comprenent el Paisatge d'Errors de l'API de Didit

Abans d'implementar qualsevol lògica de reintent, és crucial comprendre els tipus d'errors que podeu trobar. L'API de Didit, com molts serveis ben dissenyats, comunica diversos estats a través de codis d'estat HTTP. Mentre que els codis 2xx estàndard indiquen èxit, us centrareu principalment en els 4xx (errors del client) i 5xx (errors del servidor), i especialment en el 429 (Too Many Requests).

La Limitació de Velocitat de Didit i el que significa per a tu

Didit aplica limitació de velocitat per mantenir l'estabilitat de l'API. Aquest és un aspecte crític per gestionar en la vostra integració. Per exemple, els punts finals GET solen tenir un límit global de 300 sol·licituds per minut per aplicació, amb punts finals específics com session-decision (100 rpm) o session-v2-create (600 rpm) amb els seus propis límits, potencialment més estrictes. Quan arribeu a un límit de velocitat, Didit respon amb un codi d'estat 429 Too Many Requests i inclou capçaleres útils:

X-RateLimit-Limit: El nombre màxim de sol·licituds permeses a la finestra actual.
X-RateLimit-Remaining: El nombre de sol·licituds restants a la finestra actual.
X-RateLimit-Reset: El temps (en segons època) quan es restableix la finestra de límit de velocitat actual.
Retry-After: (Sovint inclòs) El nombre de segons a esperar abans de fer una altra sol·licitud.

El vostre client Go hauria de monitoritzar activament aquestes capçaleres. Quan X-RateLimit-Remaining baixi d'un cert llindar (per exemple, el 15% de X-RateLimit-Limit), hauríeu de limitar proactivament les vostres sol·licituds. Ignorar-les pot provocar errors 429 sostinguts, afectant la capacitat de la vostra aplicació per crear sessions de verificació o recuperar resultats de productes com la verificació d'identitat de Didit o la detecció AML.

Implementació d'Estratègies Robusta de Reintents amb Backoff Exponencial a Go

Per a errors transitoris (per exemple, temps d'espera de xarxa, indisponibilitat temporal del servei o 429s), els reintents són essencials. No obstant això, els reintents ingenus poden agreujar els problemes. L'estàndard d'or és el backoff exponencial amb jitter.

Backoff Exponencial amb Jitter

El backoff exponencial significa augmentar el temps d'espera entre reintents de manera exponencial. El jitter (afegir un petit retard aleatori) evita un problema de 'ramat tronador' on molts clients tornen a intentar simultàniament després d'una interrupció, sobrecarregant el servei de nou. Aquí hi ha un exemple conceptual de 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 {
			// Gestiona errors de xarxa (per exemple, connexió rebutjada, temps d'espera)
			fmt.Printf("Intent %d: Error de xarxa: %v\n", i+1, err)
			if i == maxRetries {
				return nil, fmt.Errorf("ha fallat després de %d reintents: %w", maxRetries, err)
			}
			sleepTime := time.Duration(1<<i)*time.Second + time.Duration(rand.Intn(1000))*time.Millisecond // Backoff exponencial + jitter
			fmt.Printf("Reintentant en %v...\n", sleepTime)
			time.Sleep(sleepTime)
			continue
		}
		defer resp.Body.Close()

		switch resp.StatusCode {
		case http.StatusOK:
			fmt.Printf("Intent %d: Èxit!\n", i+1)
			return ioutil.ReadAll(resp.Body)
		case http.StatusTooManyRequests:
			// Respecta la capçalera Retry-After si hi és
			retryAfter := resp.Header.Get("Retry-After")
			if retryAfter != "" {
				if sleepSeconds, err := time.ParseDuration(retryAfter + "s"); err == nil {
					fmt.Printf("Intent %d: Límit de velocitat. Reintentant després de %v.\n", i+1, sleepSeconds)
					time.Sleep(sleepSeconds)
					continue
				}
			}
			// Retorn a backoff exponencial si Retry-After falta o no és vàlid
			fmt.Printf("Intent %d: Límit de velocitat (429).\n", i+1)
			if i == maxRetries {
				return nil, fmt.Errorf("límit de velocitat després de %d reintents", maxRetries)
			}
			sleepTime := time.Duration(1<<i)*time.Second + time.Duration(rand.Intn(1000))*time.Millisecond
			fmt.Printf("Reintentant en %v...\n", sleepTime)
			time.Sleep(sleepTime)
			continue
		case http.StatusInternalServerError, http.StatusBadGateway, http.StatusServiceUnavailable, http.StatusGatewayTimeout:
			// Errors del servidor que podrien ser transitoris
			fmt.Printf("Intent %d: Error del servidor %d. Reintentant.\n", i+1, resp.StatusCode)
			if i == maxRetries {
				return nil, fmt.Errorf("error del servidor %d després de %d reintents", resp.StatusCode, maxRetries)
			}
			sleepTime := time.Duration(1<<i)*time.Second + time.Duration(rand.Intn(1000))*time.Millisecond
			fmt.Printf("Reintentant en %v...\n", sleepTime)
			time.Sleep(sleepTime)
			continue
		default:
			// Errors no reintentables (errors de client 4xx, etc.)
			body, _ := ioutil.ReadAll(resp.Body)
			return nil, fmt.Errorf("error d'API no reintentable: %d %s, resposta: %s", resp.StatusCode, resp.Status, string(body))
		}
	}
	return nil, fmt.Errorf("flux de control inesperat") // No s'hauria d'arribar aquí
}

func main() {
	// Exemple d'ús: Substitueix amb el punt final real de l'API de Didit
	// Per a una integració real, estaries fent POST a /v3/session/ o similar
	// i gestionant la verification_url.
	apiURL := "https://verification.didit.me/health"
	data, err := callDiditAPIWithRetry(apiURL, 5)
	if err != nil {
		fmt.Println("No s'ha pogut trucar a l'API:", err)
	} else {
		fmt.Println("Resposta de l'API:", string(data))
	}
}

Aquest fragment demostra com gestionar errors de xarxa, 429s (respectant Retry-After), i errors comuns 5xx amb backoff exponencial i jitter. També mostra com fallar ràpidament per errors 4xx no reintentables, que solen ser deguts a una entrada incorrecta i no es resoldran amb un reintent. Això és crucial per a operacions com la creació d'una sessió de verificació utilitzant l'arquitectura modular de Didit.

Implementació d'un Patró de Disjuntor

Tot i que els reintents ajuden amb problemes transitoris, reintentar contínuament un servei que falla pot sobrecarregar-lo encara més o malgastar recursos si el servei està realment caigut. Aquí és on entra en joc el patró de disjuntor. Un disjuntor monitoritza els errors i, si arriben a un cert llindar, "obre" el circuit, impedint futures sol·licituds durant un període determinat. Després del període, permet unes quantes sol·licituds de prova per veure si el servei s'ha recuperat.

A Go, podeu utilitzar biblioteques com sony/gobreaker per implementar aquest patró:

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, // Permet 3 sol·licituds en estat semi-obert
		Interval:    5 * time.Second, // Període per recollir dades per a decisions de tancament
		Timeout:     10 * time.Second, // Obre el circuit durant 10 segons
		ReadyToTrip: func(counts gobreaker.Counts) bool {
			return counts.ConsecutiveFailures > 5 // Tanca després de 5 errors consecutius
		},
		OnStateChange: func(name string, from gobreaker.State, to gobreaker.State) {
			fmt.Printf("El disjuntor '%s' ha canviat de %s a %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 // Error de xarxa
		}
		defer resp.Body.Close()

		if resp.StatusCode != http.StatusOK {
			// Només compte 5xx i 429 com a errors per al disjuntor
			if resp.StatusCode == http.StatusTooManyRequests || resp.StatusCode >= http.StatusInternalServerError {
				return nil, fmt.Errorf("l'API ha retornat l'estat %d", resp.StatusCode)
			}
			// Per a altres errors 4xx, potser no volem tancar el disjuntor, però igualment retornar un error
			bodyBytes, _ := ioutil.ReadAll(resp.Body)
			return nil, fmt.Errorf("error d'API no reintentable: %d %s, resposta: %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("el disjuntor està obert: %w", err)
		}
		return nil, err
	}

	return body.([]byte), nil
}

func main() {
	// Exemple d'ús
	apiURL := "https://verification.didit.me/health"
	for i := 0; i < 10; i++ {
		data, err := callDiditAPIWithCircuitBreaker(apiURL)
		if err != nil {
			fmt.Printf("La trucada %d ha fallat: %v\n", i+1, err)
		} else {
			fmt.Printf("La trucada %d ha tingut èxit: %s\n", i+1, string(data))
		}
		time.Sleep(1 * time.Second)
	}
}

La combinació de disjuntors amb backoff exponencial assegura que la vostra aplicació romangui responsiva i no sobrecarregui un servei extern amb problemes. Això és particularment important quan es tracta de sol·licituds de verificació d'identitat d'alt volum, com les que involucren la verificació d'identitat de Didit o les comprovacions de vivacitat passiva i activa.

Gestió d'Errors de Webhook i Resultats Asíncrons

L'API de Didit sovint proporciona resultats de manera asíncrona mitjançant webhooks, per exemple, després que un usuari completi un flux de verificació d'identitat o quan finalitza una comprovació AML Screening. El vostre punt final de webhook ha de ser robust. Si el vostre punt final no processa un webhook (per exemple, retorna un codi d'estat 5xx), Didit intentarà lliurar el webhook de nou. És crucial:

Reconeixement Immediat de la Recepció: Retorna un codi d'estat 2xx el més ràpidament possible per indicar la recepció correcta, fins i tot si el processament triga més.
Processament Asíncron: Lliura la càrrega útil del webhook a un treballador en segon pla o a una cua de missatges (per exemple, Kafka, RabbitMQ) per al seu processament. Això evita que el vostre punt final de webhook es quedi sense temps d'espera dels reintents de Didit.
Idempotència: Assegureu-vos que la vostra lògica de processament de webhooks sigui idempotent. Si Didit reintenta i lliura el mateix webhook diverses vegades, el vostre sistema hauria de processar-lo només una vegada per evitar accions duplicades o inconsistències de dades.
Verifica les Firmes: Verifica sempre la firma del webhook utilitzant la vostra Clau Secreta de Webhook des de la Consola de Didit per assegurar-te que la sol·licitud prové realment de Didit i no ha estat manipulada.

Com Didit Ajuda

Didit està dissenyat tenint en compte l'experiència del desenvolupador i la fiabilitat, proporcionant funcions que inherentment simplifiquen la gestió avançada d'errors i les estratègies de reintent per a les vostres integracions de Go. El nostre enfocament centrat en el desenvolupador significa una documentació d'API clara i completa, un sandbox instantani i APIs netes que fan la integració senzilla.

Limitació de Velocitat Previsible: Didit defineix clarament els límits de velocitat globals i específics per a cada punt final, juntament amb les capçaleres HTTP estàndard (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, Retry-After) per guiar la vostra lògica de limitació i backoff per part del client. Aquesta transparència us permet construir mecanismes de reintent optimitzats per a serveis com la verificació d'identitat i la detecció AML.
Arquitectura Modular: Les nostres primitives d'identitat modulars signifiquen que podeu construir fluxos de treball resilients per disseny. Si una comprovació específica (per exemple, prova d'adreça) troba un problema transitori, el vostre flux de treball general es pot configurar per adaptar-se o reintentar components específics sense afectar els passos de verificació no relacionats.
Fiabilitat Nadiua d'IA: El backend natiu d'IA de Didit està construït per a l'escala i la resiliència, minimitzant els errors del servidor que trobareu. Això us permet centrar la vostra gestió d'errors en problemes de xarxa i del costat del client, en lloc de constants interrupcions del servei.
KYC Core Gratuït i Preus Flexibles: Comenceu amb el nivell gratuït de Didit per a KYC Core, el que us permet provar a fons les vostres estratègies de gestió d'errors i reintent en un entorn similar a la producció sense costos inicials. El nostre model de pagament per comprovació reeixida alinea encara més el nostre èxit amb el vostre.

Llest per començar?

Llest per veure Didit en acció? Obteniu una demostració gratuïta avui.

Comenceu a verificar identitats de forma gratuïta amb el nivell gratuït de Didit.