Riferimento API
Errori
Struttura degli errori, tutti i codici e quando riprovare.
Struttura#
{
"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-Afterindica 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; vediGET /credits.Retry-After: 30. - La quota giornaliera di 200 conversioni gratuite PNG, PDF, TIFF e PPTX è esaurita:
details.reason = DAILY_CONVERSION_LIMIT, conRetry-Afterfino al ripristino della finestra giornaliera. - Caricamenti troppo rapidi:
details.reason = UPLOAD_RATE_LIMITEDper immagini e maschere suPOST /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_REACHEDper 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.