Idempotency & rate limit

Rendi le scritture ripetibili con Idempotency-Key, gestisci il rate limit per chiave e conosci i limiti operativi dell'API.

Due meccanismi rendono robuste le integrazioni server-to-server: l'header Idempotency-Key per evitare scritture duplicate sui retry, e il rate limit per chiave con header informativi per regolare il traffico.

Idempotency

Le rotte POST supportano l'header Idempotency-Key. Serve a garantire che un retry della stessa richiesta (per timeout, errore di rete, ecc.) non crei duplicati: Audin riconosce la chiave e ritorna la risposta originale.

Scope: solo rotte POST.
TTL: la risposta 2xx viene conservata per 24 ore associata alla chiave.
Errori non cachati: se la prima chiamata fallisce (status non-2xx), la chiave non viene persistita — puoi ritentare liberamente.
Body mismatch: se riusi la stessa chiave con un body diverso, ricevi 422 IDEMPOTENCY_KEY_MISMATCH.
Lunghezza chiave: massimo 255 caratteri. È consigliato un UUID v4.

Come funziona

Genera un UUID v4 e invialo nell'header Idempotency-Key su una richiesta POST.

Audin salva la risposta 2xx per 24 ore, associata a quella chiave.

Se la stessa chiave arriva di nuovo con lo stesso body, Audin ritorna la risposta cachata invece di creare un nuovo record.

Se la stessa chiave arriva con un body diverso, ricevi 422 IDEMPOTENCY_KEY_MISMATCH: usa una chiave fresca per la nuova operazione.

Se la prima chiamata era fallita (non-2xx), la chiave non è stata persistita: puoi semplicemente ritentare.

Esempio

IDEM=$(uuidgen)

# Prima chiamata — crea il lead
curl -X POST https://api.audin.ai/leads \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"fullName":"Mario Rossi","phoneNumber":"+393331234567"}'

# Retry identico — ritorna lo stesso lead, NON crea un duplicato
curl -X POST https://api.audin.ai/leads \
  -H "X-API-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $IDEM" \
  -d '{"fullName":"Mario Rossi","phoneNumber":"+393331234567"}'

import { randomUUID } from "node:crypto";

const idempotencyKey = randomUUID(); // UUID v4
const body = JSON.stringify({
  fullName: "Mario Rossi",
  phoneNumber: "+393331234567",
});

async function createLead() {
  return fetch("https://api.audin.ai/leads", {
    method: "POST",
    headers: {
      "X-API-Key": process.env.AUDIN_API_KEY,
      "Content-Type": "application/json",
      // Riusa la STESSA chiave per i retry della stessa operazione.
      "Idempotency-Key": idempotencyKey,
    },
    body, // stesso body a ogni retry: un body diverso → 422
  });
}

// Un retry con la stessa chiave + stesso body ritorna il lead originale.
await createLead();
await createLead();

Best practice. Usa un UUID v4 fresco per ogni operazione logicamente distinta; riusa la stessa chiave solo per ritentare quella precisa chiamata (timeout, errore di rete). Non condividere chiavi tra operazioni diverse.

Rate limit

Ogni API Key ha un limite di 100 richieste al minuto (sliding window).

Ogni risposta include header informativi che ti permettono di regolare il traffico prima di incappare nel limite:

Header	Significato
`X-RateLimit-Limit`	limite totale della finestra (`100`)
`X-RateLimit-Remaining`	richieste residue nella finestra corrente
`X-RateLimit-Reset`	unix timestamp dello sblocco della finestra
`Retry-After`	secondi da attendere (presente solo sulle risposte `429`)

Quando superi il limite ricevi 429 con un code dedicato:

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests, please try again later."
  }
}

Questo envelope con code/message è la forma usata dai controlli trasversali — il rate limiter (RATE_LIMITED, 429) e il mismatch di idempotency (IDEMPOTENCY_KEY_MISMATCH, 422) — e differisce dal formato raw { "error": "..." } delle rotte di risorsa (vedi Formato e convenzioni). Distingui i due casi sul code quando gestisci gli errori a livello di codice.

Su 429, rispetta sempre l'header Retry-After: attendi i secondi indicati prima di ritentare e implementa un backoff esponenziale (con jitter) per le richieste successive. Non ritentare in loop stretto.

Limiti operativi

Parametro	Limite
Rate limit	100 richieste / minuto per API Key
Dimensione massima del body	10 MB
`pageSize` (query param)	max 100
Webhook / push notification	Non supportati — modello polling-only
Lunghezza massima `Idempotency-Key`	255 caratteri (consigliato UUID v4)

Non esistono webhook: gli stati che evolvono nel tempo (es. la firma di un contratto) si seguono con polling periodico della risorsa. Vedi Flussi operativi.