Idempotenza e errori
Idempotenza degli invii, formato degli errori e codici di stato.
Idempotenza
Passa idempotencyKey nel body sugli invii (obbligatoria per le email, minimo 8 caratteri):
una stessa chiave non produce due invii. Non esiste un header Idempotency-Key.
Anagrafiche: la chiave naturale basta
Su contatti, liste e tag non serve una chiave: la seconda chiamata identica aggancia invece
di creare o fallire, quindi non devi cercare prima per sapere se puoi scrivere. La risposta dice
sempre cosa è successo con created, e lo stato distingue i due casi.
| Chiamata | Chiave naturale | Ripetendola |
|---|---|---|
POST /contacts | indirizzo per canale (identities) | 200 { created: false } sul contatto esistente, attributi fusi |
POST /lists | nome (maiuscole indifferenti) | 200 { created: false } con l'id della lista che c'è già |
POST /tags | nome (maiuscole indifferenti) | 200 { created: false } con l'id del tag che c'è già |
POST /lists/:id/contacts | coppia lista-contatto | added: 0, nessun doppione |
Prima volta: 201. POST /contacts risponde 409 ambiguous_identities in un solo caso, quando
le identità di una stessa richiesta appartengono a contatti diversi: fondere due contatti è
irreversibile e non lo facciamo di nostra iniziativa. La risposta porta i contactIds coinvolti,
così puoi decidere tu.
Gli attributes di un contatto esistente si fondono con i presenti: manda solo ciò che
cambia, null su una chiave la cancella. Il consent di un'identità si tocca solo se lo
dichiari: ometterlo non azzera un opt-in raccolto altrove.
Formato errori
Le risposte di errore sono JSON:
{ "error": "forbidden", "need": "email:send" }| Codice | Significato |
|---|---|
| 401 | Non autenticato (token assente o non valido) |
| 403 | Scope mancante |
| 409 | Conflitto (suppression, duplicato, indirizzo in uso) |
| 422 | Input non valido |
| 402 | Limite del piano raggiunto |