Integrações robustas dependem de convenções estáveis para status, IDs opacos, cursores e metadados, não de detalhes acidentais de um endpoint.
HTTP e códigos de status
Criações assíncronas retornam 202 Accepted enquanto o trabalho continua; leituras bem-sucedidas usam 200. Erros seguem Problem Details com code estável.
IDs e tempo
Trate file_..., job_..., task_... e project_id como strings opacas. Horários são ISO 8601 UTC; não deduza semântica da ordem dos IDs.
Paginação por cursor
Listas usam cursores opacos. Reenvie next_cursor sem alterações, preserve filtros e nunca fabrique um cursor no cliente.
Cabeçalhos operacionais
Envie Idempotency-Key em criações repetíveis e registre X-Request-ID. Respeite Retry-After e RateLimit-* antes de repetir.