Skip to main content

​
Content types

​
Response envelopes

There is more than one envelope. Which one you receive depends on where the failure occurred.

​
Controller success

​
Controller error

Controller errors generally do not include a stable code.

​
Middleware / guard error

Middleware errors carry a stable code. This is the shape to branch on for authorization and quota decisions.

​
Framework error

Framework-level failures can surface as:
In production, 5xx messages are sanitized. Do not depend on their text.
Write one decoder that accepts all four shapes, then normalize into your own error type. Check code first, then status/statusCode, then message.

​
HTTP status versus inner status

Most endpoints report HTTP status directly. Two areas are exceptions:
  • File restore and version operations return HTTP 200 even when the underlying operation failed, and carry the failure inside data.status.
  • Folder restore returns HTTP 200 with an explanatory message when the folder is not in trash.
Always inspect the body for these operations. Do not branch on HTTP status alone.

​
Identifiers

Path identifiers are UUIDs unless stated otherwise. Do not construct or guess them.

​
File naming

  • name is the display name without the extension.
  • extFile is the lowercased extension without a leading dot.
  • The reconstructed filename is name + "." + extFile when extFile is non-empty.
Do not assume name contains a dot or an extension.

​
Timestamps

Timestamps are ISO 8601 strings. Treat them as UTC; do not assume a local offset.

​
Null versus absent

  • null is meaningful: for example, effectiveFolderId: null means the bucket root.
  • An absent field means the information was not included, not that it is empty.
Do not normalize null to "" or 0 in your own models.

​
Empty success payloads

Some operations return data: "". A file delete is the notable example. This is a success, not an error. Check the HTTP status and message, not the truthiness of data.

​
Required scopes

Every documented operation lists the scope pair it needs. Storage operations require a bucket scope plus a resource scope:
  • read: buckets:read + resource read scope
  • write: buckets:write + resource write scope
  • delete: buckets:write + resource delete scope

​
Idempotency

No idempotency key header is documented. Retrying a write blindly can create duplicates or extra versions. Safe retry guidance:

​
Errors to retry

Pagination

List response shape.

Errors

Status codes and codes.

Authentication

Headers.

Playground

Request display limits.