Un’integrazione robusta dipende da convenzioni stabili per status, ID opachi, cursori e metadati, non da dettagli accidentali di un endpoint.
HTTP e codici di stato
Le creazioni asincrone restituiscono 202 Accepted mentre il lavoro continua; le letture riuscite 200. Gli errori usano Problem Details con code stabile.
ID e tempo
Tratta file_..., job_..., task_... e project_id come stringhe opache. I timestamp sono ISO 8601 UTC; non dedurre significato dall’ordine degli ID.
Paginazione a cursore
Le liste usano cursori opachi. Riutilizza next_cursor senza modificarlo, conserva i filtri e non costruire cursori lato client.
Header operativi
Invia Idempotency-Key sulle create ripetibili e conserva X-Request-ID. Rispetta Retry-After e RateLimit-* prima di riprovare.