Une intégration robuste dépend moins des noms d’endpoints que de conventions stables pour les statuts, identifiants, curseurs et métadonnées de requête.
HTTP et codes de statut
Les créations asynchrones utilisent 202 Accepted quand le travail continue; les lectures réussies utilisent 200. Les erreurs suivent Problem Details et conservent un code machine stable.
Identifiants et temps
Traitez file_..., job_..., task_... et project_id comme des chaînes opaques. Les horodatages sont ISO 8601 en UTC; ne déduisez aucune sémantique de l’ordre lexical des IDs.
Pagination par curseur
Les listes utilisent des curseurs opaques. Réutilisez next_cursor tel quel, conservez vos filtres et ne construisez jamais un curseur côté client.
En-têtes opérationnels
Envoyez Idempotency-Key sur les créations rejouables et conservez X-Request-ID. Respectez Retry-After et les en-têtes RateLimit-* avant de réessayer.