Errors

Error envelope

{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "The storage quota would be exceeded by this operation.",
    "details": { "quotaBytes": 10737418240, "usedBytes": 10736000000 }
  },
  "requestId": "req_a1b2c3d4"
}

Error codes

Code                        HTTP  Meaning
INVALID_API_KEY             401   Key missing, malformed, revoked, or unknown
EXPIRED_API_KEY             401   Key past its expiry date
UNAUTHORIZED                401   Authentication required (admin endpoints)
MISSING_PERMISSION          403   Key lacks the required permission
IP_NOT_ALLOWED              403   IP not in the key's allowlist
CUSTOMER_SUSPENDED          403   Customer or storage account suspended
CONTAINER_READ_ONLY         403   Write attempted on a read-only container
DIRECT_URLS_DISABLED        403   Direct-URL endpoints disabled on this container
CONTAINER_NOT_FOUND         404   Container name not found in your account
FILE_NOT_FOUND              404   File id not found in this container
FOLDER_NOT_FOUND            404   Folder id/path not found in this container
ITEM_NOT_FOUND              404   Item not found
JOB_NOT_FOUND               404   Job id not found
ITEM_ALREADY_EXISTS         409   Name collision at the destination
IDEMPOTENCY_CONFLICT        409   Idempotency-Key reused with a different payload
INVALID_FILE_NAME           400   File name fails validation
INVALID_FOLDER_NAME         400   Folder name fails validation
INVALID_CONTAINER_NAME      400   Container name fails validation
INVALID_PATH                400   Path contains traversal or invalid segments
VALIDATION_FAILED           400   Request body/query failed validation
METADATA_VALIDATION_FAILED  400   Metadata payload failed validation
EXTENSION_NOT_ALLOWED       400   File extension not allowed in this container
UNSUPPORTED_CONTENT_TYPE    415   Content type not allowed
QUOTA_EXCEEDED              413   Storage quota would be exceeded
FILE_TOO_LARGE              413   Upload exceeds the synchronous size limit
RATE_LIMITED                429   Too many requests — honor Retry-After
STORAGE_THROTTLED             429   Storage backend throttling — honor Retry-After
STORAGE_UNAVAILABLE      503   Storage backend temporarily unavailable
UPLOAD_FAILED               502   Upload failed in the storage backend
DOWNLOAD_FAILED             502   Download failed in the storage backend
COPY_FAILED                 502   Copy operation failed
MOVE_FAILED                 502   Move operation failed
INTERNAL_ERROR              500   Unexpected platform error

Handling guidance

• Retry RATE_LIMITED, STORAGE_THROTTLED, and STORAGE_UNAVAILABLE with exponential backoff, honoring the Retry-After header when present.
• Treat 4xx codes (other than 429) as permanent for the given request — fix the request instead of retrying.
• Log the requestId of failures; support uses it to find the exact audit record.
• Use Idempotency-Key on uploads and writes so network-level retries cannot duplicate work.