Una integración robusta se apoya en convenciones estables para estados, IDs opacos, cursores y metadatos, no en detalles accidentales de un endpoint.
HTTP y códigos de estado
Las creaciones asíncronas devuelven 202 Accepted mientras el trabajo continúa; las lecturas correctas usan 200. Los errores siguen Problem Details y un code estable.
Identificadores y tiempo
Trata file_..., job_..., task_... y project_id como cadenas opacas. Los tiempos son ISO 8601 UTC; no deduzcas semántica del orden lexicográfico de los IDs.
Paginación por cursor
Las listas usan cursores opacos. Reenvía next_cursor sin modificar, conserva los filtros y nunca construyas un cursor en el cliente.
Cabeceras operativas
Envía Idempotency-Key en creaciones reintentables y guarda X-Request-ID. Respeta Retry-After y RateLimit-* antes de reintentar.