Skip to content

Errors and conventions

Organization operations use /api/v1/org; End User operations use /api/v1/user; ticket redemption uses /api/v1/drive-downloads/{ticket} or /api/v1/drive-uploads/{ticket}. Treat resource IDs, command identities, tokens, cursors and ETags as opaque. A target ID selects a resource; it does not grant authority.

The standard error envelope for operations with documented schemas is:

{ "error": { "code": "authentication_required", "message": "Authentication required" } }

details may be present. Use the operation’s documented status and stable code, rather than parsing the human-readable message. authentication_required calls for an effective credential; validation_error calls for a corrected request; precondition_failed calls for a current-state read before intentionally preparing a new edit.

Use x-request-id to correlate requests. It is opaque and separate from business command identity.

Retain original command identity and exact content. Recover a Session command through its original interaction receipt, and read execution history separately. A new identity can authorize new work; connection closure is not a cancellation command.

Drive uploads and file writes have their own documented retry rules. Unknown external write or delete outcomes require reconciliation, not automatic resubmission.

User creation is recovered by the Organization’s externalId mapping; key issuance is reconciled through key metadata. A lost key secret requires explicit rotation. See authentication.

Follow each collection’s response schema. Where hasMore is true, pass nextCursor with the same scope and filters. Some collections return a plain envelope; pagination conventions are operation-specific.

For edits requiring If-Match, retain the exact quoted ETag. A historical command receipt is not current resource state or a fresh ETag. The API reference supplies available field and header schemas.