# Errori e codici di stato

Trovare la causa di una richiesta fallita e decidere se risolvere, aspettare o riprovare.

Riferimento canonico: https://flashdata.dev/it/docs/errors
Recensito: 2026-11-04 da FlashData

<a id="status-codes"></a>

## Codici di stato HTTP

Iniziare con lo stato HTTP, quindi leggere il codice di errore e il messaggio per la causa specifica.

| Stato | Significato | Cosa fare |
| --- | --- | --- |
| 400 | Richiesta non valida | Fissare la sorgente, campi richiesti, tipi di parametri o intestazioni di risposta prima di riprovare. |
| 401 | Autenticazione fallita | Controlla X-API-Key. Sostituire una chiave scaduta o revocata; riprovare la stessa chiave non aiuterà. |
| 402 | Crediti insufficienti | Controlla il saldo del conto. Aggiungi crediti o lascia che il proprietario dell'account risolva l'accesso prima di inviare di nuovo. |
| 403 | Accesso negato | Controllare le autorizzazioni di origine della chiave e lo stato dell'account o dell'abbonamento. |
| 404 | Non trovato | Controlla lo URL, il lavoro ID e l'account. I lavori al di fuori del tuo account o fonti consentite possono anche restituire 404. |
| 406 | Tipo di risposta non accettabile | Utilizzare Accept: application/json o text/plain. Selezionare Markdown con X-Respond-With: markdown. |
| 409 | Risultato non pronto / conflitto | Su un risultato leggere, sondare il lavoro esistente fino a che non si completa. Per altri endpoint, risolvere il conflitto descritto nel corpo. |
| 410 | Risultato scaduto | Usa una copia salvata. Ripristinare il risultato URL non può ripristinare un risultato scaduto. |
| 422 | Input non valido / lavoro fallito | Fissare i campi segnalati. Su un risultato letto, ispezionare job.error: un lavoro fallito non ha risultati di successo per prendere. |
| 429 | Limite raggiunto | Attendere Retry-After o retry_after. Ridurre il tasso di richiesta; per una coda piena in attesa, attendere i lavori esistenti a finish. |
| 500 / 502 / 503 / 504 | Servizio o guasto a monte | Retry legge con il backoff limitato. Per un timeout POST o presentazione, verificare se il lavoro è stato accettato prima di inviarlo di nuovo. |

- [Controllare le chiavi API](https://flashdata.dev/app/api-keys)
- [Crediti e prezzi](https://flashdata.dev/it/docs/guides/credits-and-billing/reference.md)
- [Limiti di tasso](https://flashdata.dev/it/docs/guides/usage-and-limits/reference.md)

<a id="response"></a>

## Leggi una risposta di errore

Gli errori API usano JSON, incluso quando si richiede un testo semplice. Il corpo differisce per punto finale. Branch sullo stato e il codice HTTP quando presente; utilizzare il messaggio o il dettaglio per spiegare il problema.

### Query API

Gli errori di query comunemente includono errore e messaggio; il codice è facoltativo. Gli errori di autenticazione possono utilizzare il successo: false invece di errore: true.

#### 400 · application/json

```json
{
  "error": true,
  "code": "unsupported_representation",
  "message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}
```


### Gestione API

Le risposte ai problemi V2 utilizzano application/problem+json. Tenere requestId per il supporto. Gli errori di convalida possono includere anche fieldErrors con campo, codice e messaggio.

#### 401 · application/problem+json

```json
{
  "type": "https://api.flashdata.dev/problems/invalid_api_key",
  "title": "Invalid API Key",
  "status": 401,
  "code": "invalid_api_key",
  "requestId": "example-request-id",
  "detail": "The API Key is invalid or unavailable."
}
```



<a id="diagnostics"></a>

## Stato di ispezione, intestazioni e corpo

Utilizzare curl --include per vedere tutti e tre. Questo esempio controlla la chiave con un account gratuito letto; non invia una query. Impostare FLASHDATA_API_KEY nel vostro ambiente prima.

### Ispezione di una risposta · cURL / Bash

```bash
curl --include --silent --show-error --max-time 20 \
  'https://api.flashdata.dev/v2/api-access/identity' \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [Configurazione dell'autenticazione](https://flashdata.dev/it/docs/guides/headers-and-authentication/reference.md)
- [Risoluzione dei problemi con il sintomo](https://flashdata.dev/it/docs/guides/troubleshooting/reference.md)

<a id="retries"></a>

## Quando riprova

Un POST ripetuto può creare un'altra domanda leggibile. Un timeout di rete non dimostra che la prima richiesta è stata respinta. Salvare il lavoro ID non appena lo ricevi.

| Situazione | Prossima azione |
| --- | --- |
| Input non valido, chiave, permesso o equilibrio | Smettila. Fissare la richiesta o lo stato del conto prima di riprovare; non loop su questi errori. |
| 429 con un suggerimento di attesa | Honor Retry-After (secondi o data HTTP), o il valore JSON retry_after in pochi secondi. Se entrambi sono presenti, utilizzare il ritardo più lungo. |
| Richiesta di informazioni: 429 / temporaneo 5xx / errore di rete | Ripristinare lo stesso GET. Senza un suggerimento di attesa, utilizzare ritardi crescenti con jitter, un numero massimo di tentativi e un limite di tempo. |
| Timeout POST o 5xx ambiguo | Mantenere il lavoro esistente ID e controllare il suo stato. Se non è stato ricevuto nessun ID, ispezionare la cronologia del lavoro prima di decidere di inviare di nuovo. |

- [Storia del lavoro](https://flashdata.dev/app/jobs)
- [Recuperare un'attività agente](https://flashdata.dev/it/docs/guides/agent-recovery/reference.md)

<a id="job-status"></a>

## Controllare un lavoro di sfondo

HTTP 200 dal punto di fine stato significa che la lettura è riuscita. Controllare job.status per sapere se l'attività è riuscita. Impostare JOB_ID al lavoro esistente; questo comando non invia una sostituzione.

| job.status | Cosa fare |
| --- | --- |
| pending / processing | Aspetta, poi fai lo stesso lavoro. Un risultato letto restituisce 409 fino al completamento. |
| completed | Recuperare e salvare il risultato. I risultati originali JSON restituiscono un reindirizzamento dello storage 302; i risultati formattati restituiscono un corpo direttamente. |
| failed | Smettere di inquinare e ispezionare job.error. Il punto finale del risultato restituisce 422 con il codice result_not_ready per un lavoro fallito. |

### Stato del lavoro di lettura · cURL / Bash

```bash
curl --fail-with-body --silent --show-error --max-time 30 \
  "https://api.flashdata.dev/v2/jobs/${JOB_ID:?Set JOB_ID}" \
  --header "X-API-Key: ${FLASHDATA_API_KEY:?Set FLASHDATA_API_KEY}" \
  --header 'Accept: application/json'
```

- [Stato di controllo · Python e cURL](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#status)
- [Recuperare i risultati completati](https://flashdata.dev/it/docs/reference/realtime-and-async/reference.md#results)
- [Progressi del lavoro Bulk](https://flashdata.dev/it/docs/reference/bulk-processing/reference.md#getBulkJob)

<a id="response-formats"></a>

## Errori di formato di risposta

| Stato / codice | Risolto |
| --- | --- |
| 400 · unsupported_representation | Impostare X-Respond-With per segnare, o rimuovere l'intestazione. |
| 406 · not_acceptable | Impostare Accept a application/json o text/plain; utilizzare UTF-8 se si specifica un set di beneficenza. |

- [Esempi di formato di richiesta e risposta](https://flashdata.dev/it/docs/guides/response-formats/reference.md)

<a id="support"></a>

## Ottieni aiuto con una richiesta

Invia il endpoint, UTC timestamp, HTTP stato, codice di errore e richiesta o lavoro ID. Rimuovere i tasti API, i token e firmato URLs dal rapporto.

- [Contatta il supporto](https://flashdata.dev/it/contact)
