Gestisci errori e paginazione dell'API REST

Un client affidabile distingue lo stato della paginazione, gli errori di autenticazione, i rifiuti di autorizzazione, i conflitti e i limiti temporanei. dosya non usa un token di continuazione per gli elenchi file.

Modello di risposta

Le risposte JSON corrette includono normalmente ok:true. Gli errori usano normalmente { "ok":false, "error":"…" }; quelli strutturati come folder_locked possono aggiungere campi. Conserva lo stato HTTP e l’intero corpo dell’errore nei log, senza dati sensibili.

GET /api/files usa page e per_page. L’oggetto pagination della risposta fornisce page, per_page, total_files e total_pages.

Passaggi

1. Richiedi la pagina 1 con spazio di lavoro, cartella, filtro, ordinamento e per_page stabili, poi mantieni invariati questi valori della query durante l’esecuzione.
2. Elabora ogni file per id, salva il numero di pagina corrente e leggi pagination.total_pages dalla stessa risposta.
3. Incrementa page finché la pagina elaborata non coincide con total_pages; non cercare un cursore, una continuazione o un campo next_page.
4. Se la risposta non indica successo, registra stato, error, Retry-After e intestazioni dei limiti senza conservare la chiave bearer.
5. In caso di 429 o di 503 riprovabile, riprova dopo Retry-After; ripeti GET, HEAD o un tentativo documentato di parte multipart, ma controlla lo stato prima di ripetere una modifica.
6. Riconcilia gli ID file elaborati alla fine, lasciando visibili gli errori irrisolti invece di segnare l’intera pagina come completata.

Regole su stato e tempi

Un 401 Invalid or expired API key richiede di verificare la credenziale o la scadenza. Un errore temporaneo nella ricerca di autenticazione restituisce invece 503 Service temporarily unavailable con Retry-After: 5. Un 403 può derivare da ambito, superficie, vincolo allo spazio di lavoro, ruolo, blocco o altra regola di accesso. Un 404 può celare intenzionalmente una risorsa nascosta o limitata. Un 409 segnala un conflitto di stato. Il corpo di un 429 riporta Too many requests.

La maggior parte delle risposte API espone X-RateLimit-Limit, X-RateLimit-Remaining e X-RateLimit-Reset. Il polling autenticato dell’elenco file ha un limite utente di 600 al minuto e passa comunque dal controllo IP di 600 ogni 60 secondi. Il traffico REST generale e l’inizializzazione dei caricamenti usano 300 al minuto per utente; un limite inferiore del piano o della chiave può intervenire prima.

Poiché la paginazione dei file usa offset, inserimenti ed eliminazioni durante la scansione possono spostare le pagine successive. Per un’esportazione stabile sospendi le modifiche concorrenti e, se non è possibile, elimina i duplicati per ID file.

Risultato previsto

Ogni pagina numerata viene elaborata al massimo una volta nell’esecuzione, ogni ID file viene riconciliato e, prima di ripetere le richieste riprovabili, si attende il ritardo indicato dal server. I rifiuti permanenti restano gestibili.

Guide correlate

• Guida rapida all’API REST
• Ambiti delle chiavi API