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

# Errori

> Struttura della risposta di errore ed elenco completo dei codici di errore restituiti dall'API Syrto.

Quando una richiesta fallisce, l'API restituisce uno stato HTTP diverso da `2xx` e un corpo JSON con un singolo oggetto `error`. Il `code` è un identificatore stabile e leggibile dalle macchine; ramifica su di esso anziché sul `message` leggibile dalle persone.

## Envelope di errore

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "No company matches that identifier.",
    "requestId": "req_018f9c2e7b7a7c3e9a1b2c3d4e5f6a7b",
    "details": [
      { "path": "path.taxId", "message": "Required" }
    ]
  }
}
```

<ResponseField name="error.code" type="string">
  Un codice di errore stabile dalla tabella qui sotto. L'insieme dei codici possibili è enumerato anche nella tua [specifica OpenAPI](/it/api/openapi).
</ResponseField>

<ResponseField name="error.message" type="string">
  Una descrizione leggibile. Può cambiare tra le release - non basarti su di essa a livello di codice.
</ResponseField>

<ResponseField name="error.requestId" type="string">
  L'id della richiesta, uguale all'header `X-Request-Id`. Citalo nelle richieste di supporto.
</ResponseField>

<ResponseField name="error.details" type="object[]">
  Presente solo per gli errori di validazione (`invalid_params`). Ogni voce ha un `path` (con prefisso `path.`, `query.` o `body.` per indicare dove si trovava il valore non valido) e un `message`.
</ResponseField>

## Codici di errore

| Codice                    | HTTP  | Significato                                                                                |
| ------------------------- | ----- | ------------------------------------------------------------------------------------------ |
| `missing_api_key`         | `401` | Nessun bearer token nell'header `Authorization`.                                           |
| `invalid_api_key`         | `401` | La API key non è riconosciuta.                                                             |
| `credits_exhausted`       | `402` | Il tuo saldo crediti è esaurito.                                                           |
| `limit_reached`           | `402` | La tua soglia d'uso per il periodo corrente è raggiunta.                                   |
| `client_not_configured`   | `403` | La key è valida ma la sua organizzazione non ha l'accesso all'API configurato.             |
| `not_entitled`            | `403` | Il tuo piano non include questo endpoint.                                                  |
| `unknown_endpoint`        | `404` | Rotta inesistente.                                                                         |
| `not_found`               | `404` | La richiesta era valida ma nessuna azienda corrisponde all'identificatore. Non addebitata. |
| `invalid_params`          | `422` | Un parametro di path o query non ha superato la validazione. Vedi `details`.               |
| `rate_limited`            | `429` | Hai superato il tuo [rate limit](/it/api/rate-limits). Vedi `Retry-After`.                 |
| `internal_error`          | `500` | Si è verificato un errore imprevisto.                                                      |
| `upstream_error`          | `502` | La fonte dati a monte ha restituito un errore.                                             |
| `auth_unavailable`        | `503` | La verifica della key è temporaneamente non disponibile. Riprova dopo una breve attesa.    |
| `entitlement_unavailable` | `503` | La verifica dei diritti è temporaneamente non disponibile. Riprova dopo una breve attesa.  |
| `upstream_timeout`        | `504` | La fonte dati a monte non ha risposto in tempo.                                            |

<Note>
  Un `not_found` (nessuna azienda corrispondente) non viene mai addebitato. Nemmeno le richieste che falliscono prima di raggiungere la fonte dati - inclusi gli errori di validazione, rate limit e diritti.
</Note>

## Riprovare

`429` e i codici `5xx` di disponibilità del servizio (`auth_unavailable`, `entitlement_unavailable`, `upstream_timeout` e `upstream_error` transitori) si possono riprovare in sicurezza. Quando è presente un header `Retry-After`, attendi almeno quel numero di secondi; altrimenti usa un backoff esponenziale. I codici `4xx` diversi da `429` indicano un problema con la richiesta o con il piano e non avranno successo riprovando.