Sfoglia la documentazione
Riferimento API
Trovare la causa di una richiesta fallita e decidere se risolvere, aspettare o riprovare.
In questa pagina
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. |
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.
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.
{
"error": true,
"code": "unsupported_representation",
"message": "X-Respond-With supports markdown. Omit the header for the original result fields."
}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.
{
"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."
}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.
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'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. |
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. |
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'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. |
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.