# Errori

Struttura degli errori, tutti i codici e quando riprovare.

Fonte: https://scifig.ai/it/docs/api/errors

## Struttura

```json
{
  "error": {
    "code": "INSUFFICIENT_CREDITS",
    "message": "Not enough credits.",
    "request_id": "a698a9af-0685-4557-9b29-ca57637748f9",
    "details": { "top_up_url": "https://scifig.ai/pricing?utm_source=api" }
  }
}
```

Scegli il comportamento in base a `error.code` e `details.reason`, mai a `message`, che può cambiare. Le risposte non contengono mai diagnostica interna.

## Codici

| Codice | HTTP | Significato | Riprova |
| --- | --- | --- | --- |
| UNAUTHORIZED | 401 | Credenziali mancanti o non valide. | No; modifica la richiesta o usa una nuova chiave |
| ACCOUNT_UNAVAILABLE | 401 | Questo account non può usare l’API. | No; modifica la richiesta o usa una nuova chiave |
| SCOPE_DENIED | 403 | Le credenziali non concedono questa autorizzazione. | No; modifica la richiesta o usa una nuova chiave |
| INVALID_REQUEST | 400 | La richiesta non è valida. | No; modifica la richiesta o usa una nuova chiave |
| IDEMPOTENCY_KEY_REQUIRED | 400 | È richiesta un’intestazione Idempotency-Key con 1–255 caratteri ASCII visibili. | No; modifica la richiesta o usa una nuova chiave |
| IDEMPOTENCY_CONFLICT | 409 | Questo Idempotency-Key è già stato usato con una richiesta diversa. | No; modifica la richiesta o usa una nuova chiave |
| IDEMPOTENCY_IN_PROGRESS | 409 | È ancora in elaborazione una richiesta con questo Idempotency-Key. | Sì, con lo stesso Idempotency-Key |
| NOT_FOUND | 404 | Non trovato. | No; modifica la richiesta o usa una nuova chiave |
| REVISION_CONFLICT | 409 | Il processo del grafico o diagramma di flusso non può essere modificato ora: `NOT_LATEST_REVISION`, `EDIT_IN_PROGRESS` oppure `PARENT_JOB_RUNNING` finché il processo padre è in esecuzione. | Solo per `PARENT_JOB_RUNNING`: dopo `Retry-After`, con la stessa chiave. Altrimenti modifica la versione più recente con una nuova chiave |
| PAYLOAD_TOO_LARGE | 413 | Il corpo della richiesta è troppo grande. | No; modifica la richiesta o usa una nuova chiave |
| INSUFFICIENT_CREDITS | 402 | Crediti insufficienti. | No; modifica la richiesta o usa una nuova chiave |
| CONTENT_REJECTED | 422 | La politica sui contenuti ha rifiutato la richiesta. Il rifiuto viene restituito come `422` alla creazione della richiesta o come `error.code` di un processo non riuscito se avviene durante l’esecuzione; i crediti vengono rimborsati in entrambi i casi. | No; modifica la descrizione o l’input e usa una nuova chiave |
| PLAN_REQUIRED | 403 | Il tuo piano non include questa opzione. | No; modifica la richiesta o usa una nuova chiave |
| RATE_LIMITED | 429 | Troppe richieste, attività per ora, conversioni al giorno o caricamenti; `details.reason` indica la causa. | Sì, con lo stesso Idempotency-Key |
| CONCURRENCY_LIMITED | 429 | Sono in esecuzione troppe attività per questo account. | Sì, con lo stesso Idempotency-Key |
| SERVICE_UNAVAILABLE | 503 | Il servizio è temporaneamente non disponibile. Riprova con lo stesso Idempotency-Key. | Sì, con lo stesso Idempotency-Key |
| TASK_FAILED | 502 | L’attività non è riuscita e i crediti sono stati restituiti. Invia una nuova richiesta con un nuovo Idempotency-Key per riprovare. | No; modifica la richiesta o usa una nuova chiave |
| INTERNAL_ERROR | 500 | Errore interno. | Sì, con lo stesso Idempotency-Key |

`INVALID_REQUEST` può includere `details.reason`, `details.field` o `details.issues` quando queste informazioni sono disponibili. I corpi oltre il limite di 256 KB per JSON o i limiti dei file per i caricamenti restituiscono `413 PAYLOAD_TOO_LARGE`. Solo `INSUFFICIENT_CREDITS` include `details.top_up_url`. Quando una richiesta di creazione fallisce dopo la creazione del processo (`429`, `503`, `409 IDEMPOTENCY_IN_PROGRESS` o `500 INTERNAL_ERROR`), `details.job_id` identifica quel processo: riprova con lo stesso Idempotency-Key o consulta `GET /jobs/{job_id}`, mai con una nuova chiave.

## Codici in un processo non riuscito

Un processo creato che poi fallisce riporta `status: "failed"` e un oggetto `error`. Oltre ai codici precedenti per le richieste rifiutate, il suo `error.code` può essere:

| error.code | Significato | Cosa fare |
| --- | --- | --- |
| TASK_TIMED_OUT | L’attività ha superato il tempo limite e i crediti sono stati rimborsati. Una generazione o modifica di illustrazione può includere `late_delivery_until`: fino a quel momento il risultato può ancora arrivare gratuitamente. | Continua a consultare il processo fino a `late_delivery_until`; altrimenti invia una nuova richiesta con una nuova chiave |
| CONTENT_REJECTED | La politica sui contenuti ha rifiutato il risultato durante l’esecuzione; i crediti sono stati rimborsati. Lo stesso codice viene restituito come `422` quando la richiesta stessa viene rifiutata alla creazione. | Modifica la descrizione o l’input e usa una nuova chiave |
| ADMISSION_INCOMPLETE | Il processo non è mai stato avviato perché un errore che consente un nuovo tentativo lo ha impedito. Nessun credito è stato usato. | Invia la stessa richiesta con lo stesso Idempotency-Key |
| TASK_NOT_FOUND | Il processo è stato ammesso, ma la relativa attività non è più reperibile. | Invia una nuova richiesta con una nuova chiave |
| TASK_FAILED | L’attività non è riuscita e i crediti sono stati rimborsati. Ogni errore del motore senza un codice pubblico proprio diventa `TASK_FAILED`; il codice del motore è in `details.reason`. | Invia una nuova richiesta con una nuova chiave |
| INTERNAL_ERROR | L’attività non è riuscita senza indicare il motivo; i crediti sono stati rimborsati. | Invia una nuova richiesta con una nuova chiave |

## Cause di una risposta 429

- Troppe richieste: 20 richieste di creazione al minuto per credenziale, 40 per account e 120 letture al minuto per credenziale. `Retry-After` indica il tempo fino al ripristino della finestra; `details.reason` è assente.
- Sono state avviate troppe attività nell’ultima ora: fino a 200 per account, condivise con il sito. `Retry-After: 30`.
- Sono in esecuzione troppe attività: `429 CONCURRENCY_LIMITED`, in base al piano e condivise con il sito; vedi `GET /credits`. `Retry-After: 30`.
- La quota giornaliera di 200 conversioni gratuite PNG, PDF, TIFF e PPTX è esaurita: `details.reason = DAILY_CONVERSION_LIMIT`, con `Retry-After` fino al ripristino della finestra giornaliera.
- Caricamenti troppo rapidi: `details.reason = UPLOAD_RATE_LIMITED` per immagini e maschere su `POST /files`, allegati di diagrammi di flusso e dati dei grafici. Si applica il limite di caricamento al minuto del sito.
- Troppi caricamenti in un giorno: `details.reason = UPLOAD_DAILY_LIMIT_REACHED` per allegati di diagrammi di flusso e dati dei grafici. Si applica il limite giornaliero di caricamento del sito.
- Rilevamenti del testo: 20 ogni 15 minuti per account, condivisi con il sito.