> ## Documentation Index
> Fetch the complete documentation index at: https://docs.youka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errori e comportamento di retry

> Formato del payload di errore, indicazioni per retry sicuri e come abbinare i retry alle chiavi di idempotenza.

# Errori e comportamento di retry

Le risposte non di successo usano questo envelope:

```json theme={null}
{
  "error": {
    "code": "SOME_CODE",
    "message": "Human-readable explanation",
    "issues": []
  }
}
```

## Indicazioni per i retry

* Riprovare in caso di errori di trasporto.
* Riprovare le scritture idempotenti con la stessa `Idempotency-Key`.
* Dopo lavoro asincrono, rileggere lo stato persistente invece di assumere che la prima risposta sia completa.

## Regole pratiche

* Considerare i guasti lato server come candidati al retry solo quando la scrittura originale ha usato una chiave di idempotenza stabile.
* Considerare gli URL di download delle esportazioni appena generati come temporanei e rileggerli da `GET /exports/{exportId}` quando serve.
* Se una mutazione è già in corso o va in conflitto con lo stato corrente, ispezionare il `code` restituito ed eseguire il retry solo quando l’operazione è ancora logicamente sicura.

## Client leggibili dalle macchine

L’SDK Node.js e la CLI distribuiti normalizzano gli errori in oggetti strutturati con:

* `code`
* `message`
* `status`
* `retryable`

Questo rende sicuro diramare la logica di automazione senza analizzare stringhe in formato libero.