# Codici e messaggi di errore

> **Traduzione italiana non ufficiale.** Originale: [Error Codes and Messages](https://affiliate-program.amazon.com/creatorsapi/docs/en-us/troubleshooting/error-codes-and-messages) · [sorgente EN](../../en/troubleshooting/error-codes-and-messages.md) · [indice](../../README.md)
>
> **Nota:** i valori di `type`, `reason`, `message` e i codici di errore nei payload sono riportati verbatim in inglese, così come li restituisce l'API. Amazon restituisce tutti i messaggi di errore in inglese per tutti i marketplace.

La Creators API restituisce risposte di errore strutturate che forniscono informazioni sui fallimenti di validazione delle richieste, sui problemi di autenticazione e sugli errori lato server. Tutti i messaggi di errore sono restituiti in inglese per tutti i marketplace.

## Struttura della risposta di errore

Tutti gli errori seguono una struttura JSON coerente con questi elementi:

* **Type:** l'identificatore del tipo di eccezione, per permettere ai client di identificarla programmaticamente (es. `ValidationException`).
* **Message:** una descrizione leggibile dell'errore per aiutarti nel debug.
* **Reason (per ValidationException, AccessDeniedException e UnauthorizedException):** un codice machine-readable che categorizza lo specifico tipo di errore di validazione, accesso o autenticazione.
* **Campi aggiuntivi (dipendenti dal contesto):** alcuni errori includono campi aggiuntivi come `resourceId`, `resourceType`, `fieldList` o `retryAfterSeconds`.

### Esempio di risposta di errore

```json
{
  "type": "ValidationException",
  "message": "Partner tag in the request is invalid or is not mapped to the store associated with your credential.",
  "reason": "InvalidPartnerTag"
}
```

## Tipi di eccezione

| Eccezione | Codice di stato HTTP | Descrizione |
| :--- | :--- | :--- |
| UnauthorizedException | 401 Unauthorized | Indica un'autenticazione mancante o errata per l'operazione. |
| ValidationException | 400 Bad Request | L'input non soddisfa i vincoli specificati dal servizio. Usa ValidationExceptionReason e fieldList per identificare i problemi specifici. |
| AccessDeniedException | 403 Forbidden | L'utente non ha accesso sufficiente per eseguire questa azione. |
| ResourceNotFoundException | 404 Not Found | La richiesta fa riferimento a una risorsa che non esiste. |
| ThrottleException | 429 Too Many Requests | La richiesta è stata negata per throttling. I client dovrebbero implementare il backoff esponenziale e riprovare. |
| InternalServerException | 500 Internal Server Error | Errore inatteso durante l'elaborazione della richiesta. I client dovrebbero riprovare con backoff esponenziale. |

> [!NOTE]
> È anche possibile inviare una richiesta valida e avere comunque degli errori. In questi casi il codice di stato HTTP è `200 Success`, ma la risposta può contenere errori. Per maggiori informazioni, vedi [Gestione degli errori](processing-of-errors.md).

## Intervalli dei codici di stato HTTP

#### Errori client 4xx

Questi errori indicano problemi con la richiesta inviata alla Creators API:
- **400 Bad Request** — ValidationException (input non valido, campi mancanti, errori di parsing)
- **401 Unauthorized** — UnauthorizedException (autenticazione mancante o non valida)
- **403 Forbidden** — AccessDeniedException (permessi insufficienti o account non idoneo)
- **404 Not Found** — ResourceNotFoundException (la risorsa richiesta non esiste)
- **429 Too Many Requests** — ThrottleException (rate limiting)

#### Errori server 5xx

Questi errori indicano problemi lato server della Creators API:
- **500 Internal Server Error** — InternalServerException (errore inatteso lato server)

## Codici Reason degli errori

Le sezioni seguenti forniscono descrizioni dettagliate e messaggi di esempio per ciascun reason code.

### Reason di ValidationException

| Reason Code | Descrizione | Messaggio di esempio |
|:---|:---|:---|
| **UnknownOperation** | L'operazione richiesta non è riconosciuta o non esiste | "The operation requested is invalid. Please verify that the operation name is typed correctly." |
| **CannotParse** | Il payload della richiesta non può essere interpretato come JSON valido | "Unable to parse the request payload. Please verify that the request body is valid JSON." |
| **FieldValidationFailed** | Uno o più campi della richiesta non hanno superato la validazione | "Request validation failed." (include l'array `fieldList` con i nomi dei campi) |
| **InvalidAssociate** | La credenziale non è collegata al partner tag per il marketplace indicato | "Your credential is not linked to the partner tag in the request for the given Marketplace." |
| **InvalidPartnerTag** | Il partner tag non è valido o non è mappato allo store | "Partner tag in the request is invalid or is not mapped to the store associated with your credential." |
| **Other** | Altro errore di validazione non coperto da reason code specifici | Varia in base allo specifico errore di validazione |

### Reason di AccessDeniedException

| Reason Code | Descrizione | Messaggio di esempio |
|:---|:---|:---|
| **AssociateNotEligible** | L'account associate non soddisfa i requisiti di idoneità per accedere alla Creators API. Il criterio attuale è che l'account abbia effettuato 10 vendite qualificate negli ultimi 30 giorni. | "Your account does not currently meet the eligibility requirements." |
| **AuthorizationFailed** | Il controllo di autorizzazione è fallito per l'operazione richiesta | "Authorization check failed for the requested operation." |
| **Other** | Accesso negato per un motivo non coperto da codici specifici | Varia in base allo specifico motivo di negazione dell'accesso |

### Reason di UnauthorizedException

| Reason Code | Descrizione | Messaggio di esempio |
|:---|:---|:---|
| **TokenExpired** | Il token di autenticazione è scaduto. Richiedi un nuovo access token con le tue credenziali. | "Authentication token has expired." |
| **InvalidToken** | Il token di autenticazione non è valido o è malformato. Verifica il formato del token e rigeneralo se necessario. | "The authentication token is invalid or malformed." |
| **InvalidIssuer** | L'emittente del token non corrisponde a quello atteso. Assicurati che la versione della credenziale nell'header della richiesta corrisponda alla region in cui è stato generato il token. | "The token issuer is invalid or does not match the expected issuer." |
| **MissingClaim** | Al token di autenticazione mancano claim obbligatori. Rigenera il token con gli scope e i claim corretti. | "The authentication token is missing required claims." |
| **MissingKeyId** | Al token di autenticazione manca l'identificatore di chiave richiesto nell'header JWT. Assicurati che la generazione del token includa il campo kid. | "The authentication token is missing the required key identifier." |
| **UnsupportedClient** | L'identificatore del client non è supportato. Verifica che le credenziali del client siano registrate per la Creators API. | "The client identifier is not supported." |
| **InvalidClient** | L'identificatore del client non corrisponde al valore atteso. Verifica di usare il client ID corretto per la tua applicazione. | "The client identifier does not match the expected value." |
| **MissingCredential** | Nella richiesta mancano le credenziali di autenticazione richieste. Includi l'header Authorization con un Bearer token valido e l'header della versione della credenziale. | "Missing authentication credentials." |
| **Other** | Controllo di autenticazione fallito per un motivo non coperto da codici specifici | Varia in base allo specifico fallimento di autenticazione |

### Dettagli di ThrottleException

Quando ricevi una `ThrottleException`, la risposta di errore può includere un campo `retryAfterSeconds` che indica quanto attendere prima di riprovare:

```json
{
  "type": "ThrottleException",
  "message": "The request was denied due to request throttling. Please verify the number of requests made per second.",
  "retryAfterSeconds": 60
}
```

### Dettagli di ResourceNotFoundException

Quando ricevi una `ResourceNotFoundException`, la risposta di errore include i campi `resourceType` e `resourceId`:

- **resourceType**: il tipo di risorsa non trovata
- **resourceId**: l'identificatore della risorsa non trovata

## Scenari di errore di esempio

### Partner tag non valido

```json
HTTP/1.1 400 Bad Request
{
  "type": "ValidationException",
  "message": "Partner tag in the request is invalid or is not mapped to the store associated with your credential.",
  "reason": "InvalidPartnerTag"
}
```

### Associate non valido

```json
HTTP/1.1 400 Bad Request
{
  "type": "ValidationException",
  "message": "Your credential is not linked to the partner tag in the request for the given Marketplace.",
  "reason": "InvalidAssociate"
}
```

### Campo mancante o non valido

```json
HTTP/1.1 400 Bad Request
{
  "type": "ValidationException",
  "message": "Request validation failed.",
  "reason": "FieldValidationFailed",
  "fieldList": ["partnerTag"]
}
```

### Token scaduto

```json
HTTP/1.1 401 Unauthorized
{
  "type": "UnauthorizedException",
  "message": "Authentication token has expired.",
  "reason": "TokenExpired"
}
```

### Token non valido

```json
HTTP/1.1 401 Unauthorized
{
  "type": "UnauthorizedException",
  "message": "The authentication token is invalid or malformed.",
  "reason": "InvalidToken"
}
```

### Associate non idoneo

```json
HTTP/1.1 403 Forbidden
{
  "type": "AccessDeniedException",
  "message": "Your account does not currently meet the eligibility requirements.",
  "reason": "AssociateNotEligible"
}
```

### Rate limiting

Questo errore si verifica quando superi il numero consentito di richieste al secondo. Quando ricevi un codice di stato 429, dovresti implementare il backoff esponenziale e riprovare la richiesta dopo aver atteso.

```json
HTTP/1.1 429 Too Many Requests
{
  "type": "ThrottleException",
  "message": "The request was denied due to request throttling. Please verify the number of requests made per second."
}
```

### Articolo non accessibile

```json
HTTP/1.1 404 Not Found
{
  "type": "ResourceNotFoundException",
  "message": "No items found for the requested item IDs.",
  "resourceType": "Item",
  "resourceId": "B08N5WRWNW"
}
```

### InternalServerException

```json
HTTP/1.1 500 Internal Server Error
{
  "type": "InternalServerException",
  "message": "An unexpected error occurred while processing your request."
}
```

---

## Rate limiting dell'endpoint token

Gli endpoint token Cognito v2.x (`creatorsapi.auth.<region>.amazoncognito.com/oauth2/token`) applicano un rate limit di **300 richieste ogni 5 minuti** per client. Questo riguarda l'endpoint token in sé, non la Creators API, quindi la forma della risposta differisce dagli errori sopra.

Gli access token sono validi per 1 ora (`expires_in: 3600`). Un client implementato correttamente richiede al massimo un token all'ora per credenziale, ben al di sotto del limite. Incappare in questo errore significa quasi sempre che stai richiedendo un nuovo token a ogni chiamata API invece di riutilizzare quello in cache.

**Risposta:**

```
HTTP/1.1 429 Too Many Requests
Retry-After: 300
Content-Type: application/json

{
  "error": "too_many_requests",
  "error_description": "Your client has exceeded the token-endpoint rate limit. This usually indicates a missing token cache — access tokens are valid for 1 hour and should be reused. To resolve this, generate new credentials from Associates Central and configure them using the latest CreatorsAPI SDK or follow the guide at https://affiliate-program.amazon.com/creatorsapi/docs/en-us/troubleshooting/error-codes-and-messages."
}
```

**Risoluzione:**

1. Mantieni l'access token in cache fino alla scadenza; riutilizzalo per ogni chiamata alla Creators API.
2. Se esegui più processi o container con lo stesso Client ID, condividi un'unica cache tra di essi.
3. Attendi il numero di secondi indicato nell'header `Retry-After` prima di riprovare.
4. Valuta la migrazione agli [SDK](../get-started/using-sdk.md) ufficiali: gestiscono automaticamente il caching e il rinnovo del token.

Gli endpoint token Login with Amazon v3.x (`api.amazon.com/auth/o2/token`, ecc.) non sono soggetti a questo limite specifico, ma valgono le stesse indicazioni sul caching.

---

## Stai migrando dalla Product Advertising API?

Se stai ancora chiamando la Product Advertising API (PA-API 5.0) e ricevi il seguente errore:

```json
HTTP/1.1 403 Forbidden
{
  "__type": "com.amazon.paapi5#AccessDeniedException",
  "Errors": [
    {
      "Code": "AccessDenied",
      "Message": "Product Advertising API is deprecated. Please migrate to Creators API using the migration guide at https://affiliate-program.amazon.com/creatorsapi/docs/en-us/migrating-to-creatorsapi-from-paapi."
    }
  ]
}
```

significa che la Product Advertising API è stata deprecata. Vedi [Migrare alla Creators API dalla PA-API](../migrating-to-creatorsapi-from-paapi.md) per le istruzioni passo passo.

---

## Best practice

- Controlla i codici di stato HTTP e interpreta il campo `reason` per una gestione specifica degli errori
- Implementa il retry con backoff esponenziale per gli errori 429 e 500
- Implementa la logica di rinnovo del token per gli errori TokenExpired
- Mantieni gli access token in cache per l'intera durata (1 ora) per evitare di raggiungere il [rate limit dell'endpoint token](#rate-limiting-dellendpoint-token)

Per maggiori informazioni, vedi [Gestione degli errori](processing-of-errors.md) e [Troubleshooting delle applicazioni](troubleshooting-applications.md).
